Audience API

The Audience API allows you to create different types of Audiences for Campaign targeting based on desired specifications.

See the Healthcare and Political verticals for specialized Audience API capabilities.

The following table describes each type of Audience:

Type	Description
Matched Audience	Upload a CSV or XLSX file with Audience details which is then matched with IQM's user database to create a custom Audience segment.
Retargeted Audience	Add a tracking tag to your website allowing you to track users who visit so they can be retargeted to receive ads in the future.
Geofarmed Audience	Define an Audience by a custom geographical area.
Campaign Audience	Retarget an Audience associated with a Campaign.
Audience Segment	Group users by common characteristics to reach specific target Audiences.
Pre-bid Audience	Select multiple pre-bid segments and group them together into an Audience.
Contextual Audience	IQM adds users to an Audience when they visit sites featuring specified keywords or URLs.
Lookalike Audience	Analyzes an existing Audience and generates a new one based on specified size and similarity percentage.
ABM Audience	Account-Based Marketing for Healthcare Campaigns.

More Resources

• Create a Contextual Audience Quickstart Guide
• Upload a Matched Audience Tutorial
• Audience Targeting and Data Management Help Center article

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 Workspace ID Header

Audience Details

Audience Details List

GET

Get a list of Audiences with basic details by desired filters.

An Audience id can be used to get more details in type-specific details endpoints. For example, a "Matched Audience" id can be used in the Matched Audience Details endpoint to get more details.

The id can also be used to perform various actions in Audience Management PUT/PATCH endpoints.

Request Schema
audienceIds array of integers	Audience IDs to filter by
audienceTypeIds array of integers	Audience Type IDs to filter by
audienceSubtypeIds array of integers	Audience Subtype IDs to filter by
owIds array of integers	Organization Workspace IDs to filter by
audienceStatusIds array of integers	Audience Status IDs to filter by
includeGenericAudience boolean	Include generic audiences
audienceTypeIdsWithAllSubtypes array of integers	Audience Type IDs to include all subtypes
pageNo integer	Page number of retrieved data
noOfEntries integer	Number of entries returned per page
sortBy string	Sorts results by specified field
searchFields array	Filter results by search fields

Response Properties

audienceId integer	Audience ID
audienceName string	Audience name
audienceTypeId integer	Audience Type ID
audienceStatusId integer	Audience Status ID
cpm number	Cost per thousand impressions
createdAt integer	Creation timestamp (epoch milliseconds)
reach integer	Audience reach
verticalId integer	Vertical ID
organizationName string	Organization name
runningCampaignCount integer	Number of running campaigns
pendingCampaignCount integer	Number of pending campaigns
pausedCampaignCount integer	Number of paused campaigns
expiredCampaignCount integer	Number of expired campaigns
startDate integer	Start date (epoch milliseconds)
endDate integer	End date (epoch milliseconds)
timezone integer	Timezone ID
regeneratedCount integer	Number of times regenerated
matchRate number	Match rate percentage
fileTotalCount integer	Total number of files
s3FileName string	S3 file name
approvalAccess boolean	Approval access permission
editAccess boolean	Edit access permission

JSON

Request Sample

{
  "audienceIds": [
    1003879,
    1003880
  ],
  "audienceTypeIds": [
    1,
    2
  ],
  "audienceSubtypeIds": [
    3,
    4
  ],
  "owIds": [
    12345,
    67890
  ],
  "audienceStatusIds": [
    1,
    2
  ],
  "includeGenericAudience": true,
  "audienceTypeIdsWithAllSubtypes": [
    1,
    2
  ],
  "pageNo": 1,
  "noOfEntries": 20,
  "sortBy": "audienceName",
  "searchFields": [
    "test audience",
    123456
  ]
}

Response 200

{
    "success": true,
    "data": {
        "totalRecords": 16,
        "filteredRecords": 16,
        "audienceList": [
            {
                "audienceId": 1142228,
                "audienceName": "Copy of Matched Audience Example",
                "audienceTypeId": 1,
                "audienceStatusId": 6,
                "createdAt": 1755812128000,
                "reach": 0,
                "verticalId": 1,
                "organizationName": "Conor's Org",
                "runningCampaignCount": 0,
                "pendingCampaignCount": 0,
                "pausedCampaignCount": 0,
                "expiredCampaignCount": 0,
                "matchRate": 0.0,
                "fileTotalCount": 5,
                "s3FileName": "1743014162776_matched_audience_example.csv",
                "approvalAccess": false,
                "editAccess": false
            },
            {
                "audienceId": 1141935,
                "audienceName": "Test",
                "audienceTypeId": 2,
                "audienceStatusId": 6,
                "createdAt": 1755208780000,
                "reach": 0,
                "verticalId": 1,
                "organizationName": "Conor's Org",
                "runningCampaignCount": 0,
                "pendingCampaignCount": 0,
                "pausedCampaignCount": 0,
                "expiredCampaignCount": 0,
                "matchRate": 0.0,
                "approvalAccess": false,
                "editAccess": false
            }
        ]
    }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        responseObject: {
          id: number;
          audienceName: string;
          audienceType: number;
          isVoterAudience: boolean;
          status: string;
          statusDisplayName: string;
          createdOn: number;
          dataCost: number;
          uniques: number;
        }[];
      };
    };
  };
}

function getAudienceDetails(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v2/audience/list',
    params: {
      query?: {
        owIds?: `string`,
        audienceTypeIds?: `string`,
        searchField?: `string`
      }
    }
  };

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

---

Basic Audience Details

POST

Get a basic list of Audience details.

Request Schema
audienceIds array of integers	Audience IDs to filter by
audienceTypeIds array of integers	Audience Type IDs to filter by
audienceSubtypeIds array of integers	Audience Subtype IDs to filter by
owIds array of integers	Organization Workspace IDs to filter by
audienceStatusIds array of integers	Audience Status IDs to filter by
includeGenericAudience boolean	Include generic audiences
pageNo integer	Page number of retrieved data
noOfEntries integer	Number of entries per page
sortBy string	Sorts results by specified field
searchFields array	Filter results by search fields

Response Properties

totalRecords integer	Total records count
filteredRecords integer	Filtered records count
audienceBasicList array of objects	Audience basic list
audienceBasicList object properties audienceId integer Audience ID audienceName string Audience name audienceTypeId integer Audience Type ID audienceSubtypeId integer Audience subtype ID isIqmIdTargeted boolean Indicates if IQM ID targeted audienceStatusId integer Audience status ID createdOn integer Creation timestamp (epoch seconds) cpm number Cost per thousand impressions reach integer Audience reach

Request Sample

{
  "audienceIds": [
    1003879,
    1003880
  ],
  "audienceTypeIds": [
    1,
    2
  ],
  "audienceSubtypeIds": [
    3,
    4
  ],
  "owIds": [
    12345,
    67890
  ],
  "audienceStatusIds": [
    1,
    2
  ],
  "includeGenericAudience": true,
  "pageNo": 1,
  "noOfEntries": 20,
  "sortBy": "audienceName",
  "searchFields": [
    "test audience",
    123456
  ]
}

Response 200

{
  "success": true,
  "data": {
    "totalRecords": 874,
    "filteredRecords": 874,
    "audienceBasicList": [
      {
        "audienceId": 1,
        "audienceName": "Sample audience name 1",
        "audienceTypeId": 1,
        "audienceSubtypeId": 1,
        "isIqmIdTargeted": true,
        "audienceStatusId": 1,
        "createdOn": 1653510068,
        "cpm": 1.5,
        "reach": 18850783
      }
    ]
  }
}

---

Audience Count by Status

POST

Get a count of Audiences by status type.

Request Schema
searchField string	Filter results by search field
owIds string	Organization Workspace IDs
audienceTypeIds string	Audience Type IDs

Response Properties

audienceStatusId integer	Audience Status ID
audienceCount integer	Audience count

JSON

Response 200

{
    "success": true,
    "data": [
        {
            "audienceStatusId": 1,
            "audienceCount": 2
        },
        {
            "audienceStatusId": 3,
            "audienceCount": 10
        },
        {
            "audienceStatusId": 6,
            "audienceCount": 4
        }
    ]
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function GetStatuswiseaudiencecount(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/audience/count-by-status',
    params: {
      query: {
        searchField: `string`,
        owIds: `string`,
        audienceTypeIds: `string`
      }
    }
  };

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

---

Audience Count by Type

GET

Get an Audience count by Audience type.

Response Properties

audienceTypeId integer	Audience Type ID
audienceCount integer	Audience count

JSON

Response 200

{
  "success": true,
  "data": [
    {
      "audienceTypeId": 1,
      "audienceCount": 10
    },
    {
      "audienceTypeId": 2,
      "audienceCount": 25
    }
  ]
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function getAudienceTypeWiseCount(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/count-by-type',
    params: {
      query?: {
        audienceTypeIds?: `string`,
        status?: `string`,
        searchField?: `string`
      }
    }
  };

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

Audience Management

Update Audience Name

PATCH

Update the name of an existing Audience.

Path Parameters
audienceId integer	Audience ID to update

Request Schema
audienceName string	New Audience name

Request Sample

{
  "audienceName": "Updated Audience Name"
}

Response 200

{
  "success": true,
  "data": {
    "message": "Changes saved successfully"
  }
}

---

Regenerate Audience

PATCH

Regenerate a failed Audience.

Path Parameters
audienceId integer	Audience ID to regenerate

Response 200

{
  "success": true,
  "data": {
    "message": "Audience regeneration initiated successfully"
  }
}

---

Get Audience Insights

GET

Get Insights details for a given Audience ID.

Path Parameters
audienceId integer	Audience ID to get Insights for

Response Properties

audience_id string	Audience ID
audience_name string	Audience name
audience_date string	Audience date (YYYY-MM-DD format)
vertical_id string	Vertical ID
vertical string	Vertical name
widgets array of objects	Widgets array containing insight data
widgets object properties title string Widget title type string Widget type (e.g., "table") data array of objects Widget data array data object properties Sr no. integer Serial number Key string Data key/label Audience Value string Audience value

Response 200

{
  "success": true,
  "data": {
    "audience_id": "1139300",
    "audience_name": "new hcp 1",
    "audience_date": "2025-06-27",
    "vertical_id": "2",
    "vertical": "Healthcare",
    "widgets": [
      {
        "title": "Audience Summary",
        "type": "table",
        "data": [
          {
            "Sr no.": 1,
            "Key": "Total Healthcare Facilities",
            "Audience Value": "14,219"
          },
          {
            "Sr no.": 2,
            "Key": "Total People",
            "Audience Value": "5,917"
          },
          {
            "Sr no.": 3,
            "Key": "Total Phones",
            "Audience Value": "4,833"
          },
          {
            "Sr no.": 4,
            "Key": "Total Emails",
            "Audience Value": "3,010"
          }
        ]
      }
    ]
  }
}

---

Create Audience Insights

POST

Generate Insights for any given Audience IDs.

Request Schema
audienceIds array of integers	Audience IDs

Response Properties

invalidSourceIds array of integers	Audience IDs not eligible for Insights
insightsData object	Insights data details
insightsData object properties id integer Insights ID typeId integer Insights Type ID statusId integer Insights Status ID sourceName string Source Audience name name string Insights name sourceId integer Audience ID createdAt integer Unix epoch timestamp of Insights creation

JSON

Response 200

{
  "success": true,
  "data": {
    "invalidSourceIds": [
      1233
    ],
    "insightsData": [
      {
        "id": 1003,
        "typeId": 1,
        "statusId": 1,
        "sourceName": "Audience - 1",
        "name": "Audience - 1_insights",
        "sourceId": 12345,
        "createdAt": 1689155409179
      },
      {
        "id": 1100,
        "typeId": 1,
        "statusId": 1,
        "sourceName": "audience 2",
        "name": "audience 2_insights",
        "sourceId": 54321,
        "createdAt": 1689155409179
      }
    ]
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          invalidSourceIds: number[];
          insightsData: {
            id: number;
            typeId: number;
            statusId: number;
            sourceName: string;
            name: string;
            sourceId: number;
            createdAt: number;
          }[];
        };
      };
    };
  };
}

function createInsightsForMatchedAudience(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/audience/insights/add',
    params: {
      query: {       
        audienceIds: `string`
      }
    },
  };

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

---

Attach Data Partner

POST

Attach a data partner to a Geofarmed Audience or a Contextual Audience.

Request Schema
audienceId integer	Audience ID
dataPartnerId integer	Data Partner ID

Request Sample

{
  "audienceId": 124,
  "dataPartnerId": 7
}

Response 200

{
  "success": true,
  "data": {
    "message": "Data partner attached successfully."
  }
}

---

Delete Audience

DELETE

Delete an Audience. Endpoint first checks two validations before deleting an Audience:

1. User's access to Audience IDs
2. Whether Audience IDs are attached to any Campaigns.

If the user is not authorized to delete an Audience, or the Audience IDs are attached to a Campaign, the request will return an error.

Query Parameters
audienceIds array of integers	Audience IDs

Response Properties

successfulAudienceIds array of integers	Audience IDs successfully deleted
failedAudienceIds array of integers	Audience IDs not eligible for deletion

JSON

Response 200

{
  "success": true,
  "data": {
    "successfulAudienceIds": [
      123456,
      123457
    ],
    "failedAudienceIds": []
  }
}

More Responses

Response 400

{
  "statusCode": 400,
  "responseObject": {
    "errorMsg": "Request body either not provided or not valid.",
    "errorCode": 400,
    "description": "uri=/api/v2/audience/delete"
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        statusCode: number;
        responseObject: {
          audienceFailedIds: string[];
          message: string;
          audienceSuccessfulIds: number[];
          status: boolean;
        };
      };
    };
  };
}

function DeleteAudience(): Promise<Responses> {
  const options = {
    method: 'PUT',
    url: 'https://api.iqm.com/api/v2/audience/delete',
    requestBody: {
      content: {
        "application/json": {
          audienceIds: `string`
        }
      }
    }
  };

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

Matched Audiences

Matched Audience Details

GET

Get Matched Audience details by ID.

Path Parameter
audienceId string	Matched Audience ID

Query Parameters
campaignTargetingRequired boolean	(Optional) Flag to indicate if campaign targeting details are returned, default: false
userDetailsRequired boolean	(Optional) Flag to indicate if user details are returned, default: false

Response Properties

audienceId integer	Audience ID
audienceName string	Audience name
audienceSubtypeId integer	Audience subtype ID
audienceStatusId integer	Audience status ID
cpm number	Cost per thousand impressions
owId integer	Organization Workspace ID
createdByUowId integer	Created by User Organization Workspace ID
createdAt integer	Unix epoch creation date (milliseconds)
reach integer	Audience reach
s3FileName string	Audience file name
s3Url string	S3 URL of the audience file
fileRowCount integer	Number of rows in the file
matchRate number	The percentage of matched records compared to a reference set
dataPartnerId integer	Data partner ID
modifiedAt string	Modified date (ISO 8601 format)
approvalAccess boolean	Indicates if user has access to approve
editAccess boolean	Indicates if user has edit access for the requested resource
whitelistedCampaignIds array	Array of whitelisted Campaign IDs
blacklistedCampaignIds array	Array of blacklisted Campaign IDs

JSON

Response 200

{
  "success": true,
  "data": {
    "audienceId": 1143824,
    "audienceName": "Download - Impression _NPI Nurse_iqvia_Filtered",
    "audienceSubtypeId": 4,
    "audienceStatusId": 3,
    "cpm": 25,
    "owId": 20489,
    "createdByUowId": 0,
    "createdAt": 1762502664000,
    "reach": 242,
    "s3FileName": "17_iltered9644451186956185605.csv",
    "s3Url": "s3://test-Client=204389/Audience=1143824/1762502664252_3524Download___Impression__NPI_Nurse_iqvia_Filtered9644451186956185605.csv",
    "fileRowCount": 1829,
    "matchRate": 13.23,
    "dataPartnerId": 5,
    "modifiedAt": "2025-11-07T02:42:33.000+00:00",
    "approvalAccess": false,
    "editAccess": true
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          audienceId: number;
          audienceName: string;
          audienceSubtypeId: number;
          audienceStatusId: number;
          cpm: number;
          owId: number;
          createdByUowId: number;
          createdAt: number;
          reach: number;
          s3FileName: string;
          s3Url: string;
          fileRowCount: number;
          matchRate: number;
          dataPartnerId: number;
          modifiedAt: string;
          approvalAccess: boolean;
          editAccess: boolean;
          whitelistedCampaignIds: number[];
          blacklistedCampaignIds: number[];
        };
      };
    };
  };
}

function getMatchedAudienceDetails(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/matched/{audienceId}',
    params: {
      path: {
        audienceId: `number`
      },
      query: {
        campaignTargetingRequired: `boolean`,
        userDetailsRequired: `boolean`,
      }
    }
  };

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

---

Create Matched Audience

POST

Create a Matched Audience by uploading a file with user data. The metadata is sent as a JSON string in the audienceRequest form data field, and the file is uploaded as multipart/form-data in the file form data field.

Request Schema
audienceRequest form data required	Audience metadata details
file multipart/form-data required	File to be uploaded

audienceRequest Properties

audienceName string	Audience Name
fileRowCount integer	Number of rows in the file
fileColumnCount integer	Number of columns in the file
audienceSubtypeId integer	Audience Subtype ID
columnMappings array	Array of column mapping objects
columnMappings object properties columnId integer Column ID fileColumnName string File column name dataFormatId integer Data Format ID
dataPartnerId integer	Data Partner ID
columnCombinationId integer	Column Combination ID

audienceRequest sample object for Political Matched Audience

{
  "audienceName": "matched-audience-example-fs",
  "fileRowCount": 5,
  "fileColumnCount": 10,
  "columnMappings": [
      {
          "columnId": 5,
          "fileColumnName": "l2-voter-id",
          "dataFormatId": null
      },
      {
          "columnId": 6,
          "fileColumnName": "email",
          "dataFormatId": 1
      }
  ],
  "dataPartnerId": 2,
  "columnCombinationId": 11
}

audienceRequest sample object for Healthcare Matched Audience

{
  "audienceName": "Revamped Healthcare Matched Audience 02",
  "dataPartnerId": 7,
  "audienceSubtypeId": 3,
  "columnMappings": [
      {
          "columnId": 18,
          "fileColumnName": "NPI_ID"
      }
  ],
  "fileRowCount": 19,
  "fileColumnCount": 1,
  "columnCombinationId": 14,
  "consentGiven": true
}

Select exampleForm Data SamplecURL Sample

POST /api/v3/audience/matched HTTP/1.1
Host: api.iqm.com
Authorization: Bearer 0ed52da8-24ab-44b1-bc88-7ea03a090d24
X-IAA-OW-ID: 1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="audienceRequest"
Content-Type: application/json

{"audienceName":"Healthcare Patient Audience 2025","dataPartnerId":7,"audienceSubtypeId":3,"columnCombinationId":14,"fileRowCount":1200,"fileColumnCount":3,"consentGiven":true,"columnMappings":[{"columnId":18,"fileColumnName":"NPI_ID"},{"columnId":19,"fileColumnName":"first_name"},{"columnId":20,"fileColumnName":"last_name"}]}
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="file"; filename="patient-data.csv"
Content-Type: text/csv

[Binary CSV file data]
------WebKitFormBoundary7MA4YWxkTrZu0gW--

curl -X POST https://api.example.com/api/v3/audience/matched \
  -H "Authorization: Bearer 0ed52da8-24ab-44b1-bc88-7ea03a090d24" \
  -H "X-IAA-OW-ID: 1" \
  -F 'audienceRequest={"audienceName":"Healthcare Patient Audience 2025","dataPartnerId":7,"audienceSubtypeId":3,"columnCombinationId":14,"fileRowCount":1200,"fileColumnCount":3,"consentGiven":true,"columnMappings":[{"columnId":18,"fileColumnName":"NPI_ID"},{"columnId":19,"fileColumnName":"first_name"},{"columnId":20,"fileColumnName":"last_name"}]};type=application/json' \
  -F 'file=@/path/to/patient-data.csv;type=text/csv'

Response 200

{
  "success": true,
  "data": {
    "matchedAudienceId": 12345,
    "message": "Matched audience created successfully"
  }
}

---

Update Matched Audience

PATCH

Update a Matched Audience.

Path Parameter
audienceId integer	Matched Audience ID

Request Schema
dataCost number	Data cost
audienceStatusId integer	Audience Status ID
rejectionReason string	Reason for rejection if updating status to Rejected

Response Properties

id integer	Audience ID
message string	Success message

JSON

Request Sample

{
  "dataCost": 10,
  "audienceStatusId": 4,
  "rejectionReason": "Insufficient data quality."
}

Response 200

{
  "statusCode": 200,
  "responseObject": {
    "id": 1,
    "message": "Your changes have been saved successfully"
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json;charset=UTF-8": {
        statusCode: number;
        responseObject: {
          id: number;
          message: string;
        };
      };
    };
  };
}

function EditMatchedAudience(): Promise<Responses> {
  const options = {
    method: 'PATCH',
    url: 'https://api.iqm.com/api/v3/audience/matched/{audienceId}',
    params: {
      path: {
        audienceId: `string`
      }
    },
    requestBody: {
      content: {
        "application/json": {
          dataCost: `number`,
          audienceStatusId: `number`,
          rejectionReason: `string`
        }
      }
    }
  };

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

---

Data Partners List for Matched Audience

GET

Returns a list of data partners relevant for Audiences based on vertical and optional subtype.

• For advertiser users, vertical is derived from the logged-in user's OWID.
• For workspace/super users, a vertical ID should be passed explicitly.
• Audience type ID is mandatory to fetch data partners.
• If a subtype ID is passed, it must be valid for the vertical.
• Data partners shown are based on active configurations.

Query Parameters
audienceTypeId integer required	Audience Type ID
audienceSubtypeId integer	Audience Subtype ID
verticalId integer	Vertical ID

Response Properties

id integer	Data partner ID
name string	Data partner name
order integer	Display order
displayName string	Data partner display name
cpm integer	Cost per mille (CPM)
logoUrl string	URL to data partner logo

JSON

Response 200

{
  "success": true,
  "data": [
    {
      "id": 7,
      "name": "hl_npi_id",
      "order": 6,
      "displayName": "Healthlink ID",
      "cpm": 10,
      "logoUrl": "https://cdn.com/data_partner/hld.png"
    },
    {
      "id": 8,
      "name": "data360_npi_id",
      "order": 7,
      "displayName": "Data360 ID",
      "cpm": 15,
      "logoUrl": "https://cdn.com/data_partner/D360.png"
    }
  ]
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json;charset=UTF-8": {
        success: boolean;
        data: {
          id: number;
          label: string;
          keyName: string;
          audienceColumnId: number;
        }[];
      };
    };
  };
}

function getMatchedAudienceDataPartner(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/static/matched/data-partner',
  };

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

---

Data Formats List for Matched Audience

GET

Get a static list of Matched Audience hashed data formats.

Response Properties

id integer	Data format ID
name string	Data format name
order integer	Display order
displayName string	Data format display name

JSON

Response 200

{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Raw",
            "order": 1,
            "displayName": "Raw"
        },
        {
            "id": 2,
            "name": "MD5",
            "order": 2,
            "displayName": "Hashed (MD5)"
        },
        {
            "id": 3,
            "name": "SHA1",
            "order": 3,
            "displayName": "Hashed (SHA1)"
        },
        {
            "id": 4,
            "name": "SHA256",
            "order": 4,
            "displayName": "Hashed (SHA256)"
        },
        {
            "id": 5,
            "name": "SHA512",
            "order": 5,
            "displayName": "Hashed (SHA512)"
        },
        {
            "id": 6,
            "name": "Other",
            "order": 6,
            "displayName": "Hashed (other)"
        }
    ]
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json;charset=UTF-8": {
        success: boolean;
        data: {
          id: number;
          label: string;
          keyName: string;
        }[];
      };
    };
  };
}

function getMatchedAudienceDataFormats(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/static/data-formats',
  };

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

---

Matched Column List

GET

Returns a list of matched Audience columns along with its supported data format ids based on vertical and optional Audience subtype.

• For advertiser users, vertical is inferred from the logged-in user's owId.
• For workspace/super users, vertical ID should be passed explicitly.
• If both passed and inferred vertical IDs conflict, the request will be rejected.
• If a subtype is provided, it must belong to the specified vertical. Note: if there is no column combination found, it will return an empty list.

Query Parameter
verticalId integer optional	Vertical ID
audienceSubtypeId integer optional	Audience Subtype ID

Response Properties

id integer	Column ID
name string	Column name
order integer	Display order
displayName string	Column display name
dataFormatIds array	Array of supported data format IDs for this column

Response 200

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Voters_ID",
      "order": 1,
      "displayName": "Voter ID"
    },
    {
      "id": 2,
      "name": "Email",
      "order": 3,
      "displayName": "Email",
      "dataFormatIds": [
        1,
        2,
        3,
        4,
        5,
        6
      ]
    },
    {
      "id": 3,
      "name": "Phone",
      "order": 4,
      "displayName": "Phone",
      "dataFormatIds": [
        1,
        2,
        3,
        4,
        5,
        6
      ]
    }
  ]
}

---

Matched Column Combinations

GET

Returns a list of matched Audience column combinations based on vertical and optional Audience subtype.

• For advertiser users, vertical is inferred from the logged-in user's owId.
• For workspace/super users, vertical ID should be passed explicitly.
• If both passed and inferred vertical IDs conflict, the request will be rejected.
• If a subtype is provided, it must belong to the specified vertical.

Query Parameter
verticalId integer optional	Vertical ID
audienceSubtypeId integer optional	Audience Subtype ID

Response Properties

id integer	Combination ID
columnIds array	Array of Column IDs in this combination
order integer	Display order

Response 200

{
  "success": true,
  "data": [
    {
      "id": 1,
      "columnIds": [
        1,
        2,
        3,
        4
      ],
      "order": 1
    },
    {
      "id": 3,
      "columnIds": [
        3,
        4,
        8,
        9
      ],
      "order": 4
    },
    {
      "id": 5,
      "columnIds": [
        7,
        8,
        4,
        9
      ],
      "order": 6
    }
  ]
}

---

Download Matched Audience File

GET

Get a presigned S3 URL to download a Matched Audience file.

Path Parameters
audienceId integer	Matched Audience ID to download file for

Response Properties

matchedAudienceFileUrl string

Presigned S3 URL to download Matched Audience file

Response 200

{
  "success": true,
  "data": {
    "matchedAudienceFileUrl": "https://cdn.com/CAM-FILES/Client%3D204389/Audience%3D1143824/1762502664252_3524Download___Impression__NPI_Nurse_iqvia_Filtere6956185605.csv?response-content-disposition=attachment%3Bfilename%3D%2217664252_3524Download___Impression__NPI_Nurse_iqvia_Filtered9185605.csv%22&response-content-type=application%2Foctet-stream&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIABRMU%2F20251205%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20251205T121547Z&X-Amz-Expires=120&X-Amz-SignedHeaders=host&X-Amz-Security-Token=IQoJAWPe%2FrI%3D&X-Amz-Signature=19fb8f0208181cd011414bad4e3e"
  }
}

Segmented Audiences

Segmented Audience Details

GET

Get Segmented Audience details by ID.

Path Parameter
audienceId string	Audience ID

Response Properties

audienceId integer	Audience ID
audienceName string	Audience name
audienceStatusId integer	Audience Status ID
createdAt integer	Creation timestamp (epoch seconds)
uniques integer	Count of unique audiences reached
cpm number	Cost per mille
editAccess boolean	Indicates if user has edit access for the requested resource
segmentPartnerName string	Segment partner name
segmentPartnerId integer	Segment Partner ID
segmentPartnerLogo string	Segment partner logo URL
equation string	Equation string describing the or-and relationship between Segment groups
segmentsList array of objects	Array of Segmented Audiences
segmentsList object properties segmentId integer Segmented Audience ID taxonomyId string Taxonomy category ID taxonomyValue string Value associated with taxonomy category description string Description pathKey string A hierarchical key representing the taxonomy's path or structure cpm number Cost per mille modifiedAt string Date last modified totalReach integer Total number of reach in terms of devices reachMetadata object Reach metadata object, breakdown by device type reachMetadata object properties iosDevicesReach integer iOS devices reach androidDevicesReach integer Android devices reach cookiesReach integer Cookies reach dataAvailable boolean Indicates whether relevant data is available for this taxonomy leafNode boolean Indicates whether this taxonomy is a final node (i.e. it has no subcategories)

JSON

Response 200

{
  "success": true,
  "data": {
    "audienceId": 1076846,
    "audienceName": "Test kishan 19,04:50",
    "audienceStatusId": 3,
    "createdAt": 1718796428,
    "uniques": 0,
    "cpm": 1.5,
    "editAccess": true,
    "segmentPartnerName": "LiveRamp",
    "segmentPartnerId": 1,
    "segmentPartnerLogo": "https://s3.amazonaws.com/advp0had0vuj7rad3niaw1eus2/data_partner/liveramp.png",
    "equation": "((5586112|6450431)&(14005))",
    "segmentsList": [
      {
        "segmentId": 14005,
        "taxonomyId": "1000143856",
        "taxonomyValue": "Western Samoa",
        "description": null,
        "pathKey": "LiveRamp > L2 Political > L2 Voter Data > Individual Demographics > Ethnicity > Ethnic Description > Western Samoa",
        "cpm": 1.5,
        "modifiedAt": "2021-06-08 08:45:50.979634",
        "totalReach": 0,
        "reachMetadata": null,
        "dataAvailable": false,
        "leafNode": true
      },
      {
        "segmentId": 5586112,
        "taxonomyId": "1007595031",
        "taxonomyValue": "South Dakota-13",
        "description": "30 day full data refresh: Individuals living in the South Dakota-13 state senate district. For political use only.",
        "pathKey": "LiveRamp > 123Push > Optimized for CTV > Voters > State Senate District > South Dakota-13",
        "cpm": 0.75,
        "modifiedAt": "2021-06-08 08:45:50.979634",
        "totalReach": 14800,
        "reachMetadata": null,
        "dataAvailable": false,
        "leafNode": true
      },
      {
        "segmentId": 6450431,
        "taxonomyId": "1000037244",
        "taxonomyValue": "Voted In the 2004 Primary Election",
        "description": "This segment contains users who voted in the General Election of this election year",
        "pathKey": "LiveRamp > Porch Group Media (fka V12) > V12 > NEW VOTER & INCOME > Voted In the 2004 Primary Election",
        "cpm": 0.5,
        "modifiedAt": "2024-05-07 09:52:51.191186",
        "totalReach": 5100000,
        "reachMetadata": {
          "iosDevicesReach": 2200000,
          "androidDevicesReach": 2900000,
          "cookiesReach": 0
        },
        "dataAvailable": false,
        "leafNode": true
      }
    ]
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          id: number;
          name: string;
          status: string;
          type: number;
          includedCount: number;
          excludedCount: number;
          createdOn: number;
          organizationName: string;
          owId: number;
          createdByUowId: number;
          createdByUserEmail: string;
          uniques: number;
          dataCost: number;
          segmentsList: {
            segmentId: number;
            taxonomyId: number;
            taxonomyValue: number;
            description: string;
            pathKey: string;
            cpm: number;
            lastUpdatedDate: string;
            totalReach: number;
            reachMetadata: string;
            dataAvailable: boolean;
            leafNode: boolean;
          }[];
          segmentPartnerName: string;
          segmentPartnerId: number;
          segmentPartnerLogo: string;
          equation: string;
          segmentIdList: number[];
          editAccess: boolean;
        }
      };
    };
  };
}

function getSegmentAudienceGroup(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/segment/{audienceId}',
    params: {
      path: {
        audienceId: `number`
      }
    }
  };

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

---

Search Segmented Audiences

POST
POST

Retrieves the segments search list based on the provided request parameters. Allows filtering segments based on various criteria such as search fields, segment IDs, provider, price range, and more. Search results can be downloaded as a CSV file using the download endpoint.

Request Schema
pageNo integer	Page number for the required data, default: 1
noOfEntries integer	Maximum number of returned results per page, default: 100
sortBy string	Sorts results by specified field. For ascending use plus(+) sign and for descending use minus (-) sign
searchKeywordSet array of strings	Search keywords to be searched on the 'pathKey' and 'description' of the segments with encoded special characters (required if segmentIds not given)
segmentIds array of integers	Segment IDs to filter returned data by (required if searchKeywordSet not given)
verticalIds array of integers	Vertical IDs to filter returned data by
partnerIds array of integers	Partner IDs to filter returned data by
providerIds array of integers	Provider IDs to filter returned data by
priceRangeIds array of integers	Price Range IDs to filter returned data by
reachRangeIds array of integers	Reach Range IDs to filter returned data by
showOnlyReadySegments boolean	Flag to filter segments that are ready, default: false
showOnlyNonZeroSegments boolean	Flag to filter segments that have non-zero reach, default: false

Response Properties

segmentId integer	Segment ID
taxonomyValue string	Taxonomy value
description string	Description
pathKey string	A hierarchichal key representing the taxonomy's path or structure
cpm integer	Cost per mille
referenceId string	Reference ID
lastUpdateDate string	Date when last updated
totalReach integer	Total reach
providerId integer	Provider ID
partnerId integer	Partner ID
reachMetadata object	Reach metadata object details
reachMetadata object properties iosDevicesReach integer IOS devices reach androidDevicesReach integer Android devices reach cookiesReach integer Cookies reach
logoUrl string	Logo URL

JSON

Request Sample

{
  "searchKeywordSet": [
    "sample 1",
    "sample 2"
  ],
  "sortBy": "-reach",
  "verticalIds": [
    1,
    2,
    3
  ],
  "partnerIds": [
    1,
    2,
    3
  ],
  "providerIds": [
    1,
    2,
    3
  ],
  "priceRangeIds": [
    1,
    2,
    3
  ],
  "reachRangeIds": [
    1,
    2,
    3
  ],
  "segmentIds": [
    1,
    2,
    3
  ],
  "showOnlyReadySegments": true,
  "showOnlyNonZeroSegments": true
}

Response 200

{    
  "success": true,    
  "data": {        
    "filteredRecords": 45,        
    "segmentsList": [            
      {                
        "segmentId": 5830140,                
        "taxonomyValue": "Thriller/Horror",                
        "description": "This audience contains people that are likely to watch Thriller/Horror TV content & are CBD purchasers. Data leverages Comscore's deterministic, single-source cross-platform dataset derived from set-top box (STB) data from households exposed to the target viewing criteria & is cultivated from industry-leading endemic companies (Point of Sale systems, eCommerce platforms, Delivery services, and Loyalty/CRM platforms).",                
        "pathKey": "LiveRamp > Fyllo > Fyllo > Infused > Comscore > TV > Genre > Thriller/Horror",                
        "cpm": 1.5,                
        "referenceId": "a5b286f2-3b48-42b1-a0d3-1c349aa8800b",                
        "lastUpdatedDate": "2021-07-04T10:48:42.296+00:00",                
        "totalReach": 6000000,                
        "providerId": 140,                
        "partnerId": 1,                
        "dataAvailable":true,                 
        "reachMetadata": {                   
          "iosDevicesReach":120,                    
          "androidDevicesReach":120,                   
          "cookiesReach":120                
        },                
        "logoUrl": "https://s3.amazonaws.com/advp0had0vuj7rad3niaw1eus2/data_partner/liveramp.png"            
      },            
      {                
        "segmentId": 6164189,                
        "taxonomyValue": "Thriller Crime & Mystery Films",                
        "description": "ShareThis collects data from its network of 600 million publisher pages capturing site visitors' pageviews, clicks, shares, and searches.  ShareThis processes these signals and uses associated keywords and topics to build out its audience. ShareThis CTV targeting allows you to leverage this online behavioral data for CTV campaigns, merging the performance of online interest data with the impact and engagement of TV.",                
        "pathKey": "LiveRamp > ShareThis > ShareThis > ShareThis for TV > Arts & Entertainment > Movies > Thriller Crime & Mystery Films",                
        "cpm": 2.0,                
        "referenceId": "e2b856fd-8777-42f1-b916-1f3042ed290d",                
        "lastUpdatedDate": "2021-12-03T11:19:19.763+00:00",                
        "totalReach": 8600000,                
        "providerId": 21,                
        "partnerId": 1,                
        "dataAvailable":true,                 
        "reachMetadata": {                   
          "inputRecordsReach":120,                   
          "iosDevicesReach":120,                    
          "androidDevicesReach":120,                   
          "cookiesReach":120                
        },                
        "logoUrl": "https://s3.amazonaws.com/advp0had0vuj7rad3niaw1eus2/data_partner/liveramp.png"            
      }        
    ]    
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json;charset=UTF-8": {
        statusCode: number;
        responseObject: {
          "0d5fcaea-0fe3-4b10-ba62-168f3dcb0281": {
            description: string;
            cpm: number;
            isLeaf: number;
            margin: number;
            pathKey: string;
            id: string;
            taxonomy_value: string;
          }[];
        };
      };
    };
  };
}

function GetSegmentSearchResult(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/audience/segmented/search/list',
    requestBody: {
      content: {
        "application/json": {
          pageNo?: `number`,
          noOfEntries?: `number`,
          sortBy?: `string`,
          searchKeywordSet?: `string[]`,
          segmentIds?: `number[]`,
          verticalIds?: `number[]`,
          partnerIds?: `number[]`,
          providerIds?: `number[]`,
          priceRangeIds?: `number[]`,
          reachRangeIds?: `number[]`,
          showOnlyReadySegments?: `boolean`,
          showOnlyNonZeroSegments?: `boolean`,
        }
      }
    }
  };

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

---

Create Segmented Audience

POST

Creates a segmented audience based on the provided request parameters. Allows creating a new segmented audience with the specified details.

Using Segment IDs (from the Master API), you can build an Audience with the equation field. Segment IDs in parentheses, separated by a vertical bar (|), will be in an 'or' relationship, which will combine the sets of Segments; groups of Segments in parentheses, separated by an ampersand (&), will be in an 'and' relationship, which will build an Audience based on the intersection of those groups. You can see an example of this format in the Request Sample code block on the right-hand side of the page.

Request Schema
equation string required	Equation string representing the segment ID groups in AND/OR relationship
audienceName string required	Name of the segmented audience to be created (maximum 255 characters)

Response Properties

id integer	Audience ID
message string	Success message

JSON

Request Sample

{
  "equation": "((6388749|6388750)&(6388751|6402730|6392754|5776004))",
  "audienceName": "football-temp"
}

Response 200

{
  "success": true,
  "data": {
    "audienceId": 1140623,
    "message": "<Audience Name> audience created successfully"
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function createSegmentAudienceGroup(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/audience/segmented',
    requestBody: {
      content: {
        "application/json": {
          equation: `string`,
          audienceName: `string`,
        }
      }
    }
  };

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

---

Update Segmented Audience

PUT

Updates an existing segmented audience based on the provided request parameters. Allows modifying the details of an existing segmented audience (name and segments).

Path Parameter
audienceId integer	Audience ID

Request Schema
equation string required	Equation string representing the segment ID groups in AND/OR relationship
audienceName string required	Name of the segmented audience to be updated (maximum 255 characters)

Response Properties

audienceId integer	Audience ID
message string	Success message

JSON

Request Sample

{
  "equation": "((5613837|5638265)&(5613844))",
  "name": "Segment audience - 1"
}

Response 200

{
  "success": true,
  "data": {
    "audienceId": 1140623,
    "message": "<Audience Name> audience updated successfully"
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function updateSegmentAudienceGroup(): Promise<Responses> {
  const options = {
    method: 'PUT',
    url: 'https://api.iqm.com/api/v3/audience/segment/{audienceId}',
    params: {
      path: {
        audienceId: `number`,
      }
    },
    requestBody: {
      content: {
        "application/json": {
          advertiserId?: `number`,
          dspId?: `number`,
          owId?: `number`,
          uowId?: `number`,
          name?: `string`,
          equation?: `string`,
        }
      }
    }
  };

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

---

Segment Partner Provider List

GET

Get a list of partners and providers with basic Audience information.

Response Properties

partnerId integer	Partner ID
partnerName string	Partner name
partnerLogoUrl string	Partner logo URL
description string	Partner description
verticalIds array of integers	List of Vertical IDs
displayOrder integer	Display order
seatId integer	Seat ID
providers array of objects	Array of Provider details
providers object properties providerId integer Provider ID providerName string Provider name providerLogoUrl string Provider logo URL description string Provider description verticalIds array of integers List of Vertical IDs
isCustomPartner boolean	Indicates whether partner is custom
isPartnerPublic boolean	Indicates whether partner is public (true) or private (false)

JSON

Response 200

{
  "success": true,
  "data": [
    {
      "partnerId": 6,
      "partnerName": "IQM Political",
      "partnerLogoUrl": "https://www.sample-domain/data_partner/iqm-political-provider.svg",
      "description": "IQM Political",
      "verticalIds": [
        1
      ],
      "displayOrder": 2,
      "providers": [
        {
          "providerId": 76,
          "providerName": "AdMavin",
          "providerLogoUrl": "https://www.sample-domain.com/iqm-political-provider.svg",
          "description": "AdMavin",
          "verticalIds": [
            1
          ]
        },
        {
          "providerId": 279,
          "providerName": "Aristotle",
          "providerLogoUrl": "https://www.sample-domain.com/iqm-political-provider.svg",
          "description": "Aristotle",
          "verticalIds": [
            1
          ]
        }
      ],
      "isCustomPartner": false,
      "isPartnerPublic": false
    },
    {
      "partnerId": 13033,
      "partnerName": "OL's Healthcare",
      "partnerLogoUrl": "https://www.sample-domain.com/avatar/OH.png",
      "description": "Seat ID: 203775",
      "seatId": 203775,
      "displayOrder": 0,
      "isCustomPartner": true,
      "isPartnerPublic": false
    }
  ]
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          partnerProviderList: {
            partnerId: number;
            partnerReferenceUuid: string;
            partnerName: string;
            partnerLogoUrl: string;
            partnerDescription: string;
            order: number;
            verticalIdList: number[];
            seatId: number;
            customPartner: boolean;
            providerList: {
              providerId: number;
              providerReferenceUuid: string;
              providerName: string;
              providerLogoUrl: string;
              verticalIdList: number[];
              providerDescription: string;
            }[];
            isPartnerPublic: boolean;
          }[];
          totalRecords: number;
          filteredRecords: number;
        }
      };
    };
  };
}

function getSegmentPartnerProviderList(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/segmented/partner-provider/list',
    requestBody: {
    }
  };

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

---

Segment List by Provider/Partner IDs

GET

Get a list of Segments by given provider or parent ID. If parent ID is not provided, endpoint will return all direct segments of a given provider ID.

Query Parameters
partnerId integer required	Partner ID
providerId integer required	Provider ID
parentId integer	Parent ID, if not provided returned results will include all direct segments of provided ID
showOnlyNonZeroSegments boolean	Returns segments with reach greater than 0: true, default: false
showOnlyReadySegments boolean	Returns segments with "ready" status: true

Response Properties

segmentId integer	Segment ID
taxonomyValue string	Taxonomy value
description string	Description
pathKey string	A hierarchichal key representing the taxonomy's path or structure
cpm number	Cost per mille
modifiedAt string	Date last modified
totalReach integer	Total number of reach in terms of devices
reachMetadata object	Reach metadata object, breakdown by device type
reachMetadata object properties iosDevicesReach integer iOS devices reach androidDevicesReach integer Android devices reach cookiesReach integer Cookies reach
dataAvailable boolean	Indicates whether relevant data is available for this taxonomy
leaf boolean	Indicates whether this taxonomy is a final node (i.e. it has no subcategories)

JSON

Response 200

{
  "success": true,
  "data": [
    {
      "segmentId": 6192803,
      "taxonomyValue": "Giving And Investment",
      "description": "Sample description",
      "pathKey": "LiveRamp > i360 > i360 > Demographics > Giving And Investment",
      "cpm": 10,
      "modifiedAt": "2021-06-08T03:15:50.979+00:00",
      "totalReach": 360,
      "dataAvailable": true,
      "reachMetadata": {
        "iosDevicesReach": 120,
        "androidDevicesReach": 120,
        "cookiesReach": 120
      },
      "leaf": false
    },
    {
      "segmentId": 6192796,
      "taxonomyValue": "Ages 18 To 29",
      "description": "Individuals Ages 18 And 29.",
      "pathKey": "LiveRamp > i360 > i360 > Demographics > Ages 18 To 29",
      "cpm": 1,
      "modifiedAt": "2021-06-08T03:15:50.979+00:00",
      "totalReach": 360,
      "reachMetadata": {
        "iosDevicesReach": 120,
        "androidDevicesReach": 120,
        "cookiesReach": 120
      },
      "leaf": true
    }
  ]
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          segmentId: number;
          taxonomyId: string;
          taxonomyValue: string;
          description: string;
          pathKey: string;
          cpm: number;
          referenceId: string;
          lastUpdateDate: string;
          totalReach: number;
          dataAvailable: boolean;
          reachMetadata: {
            iosDevicesReach: number;
            androidDevicesReach: number;
            cookiesReach: number;
          };
          leafNode: boolean;
        }[];
      };
    };
  };
}

function getSegmentsListByParent(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/segmented/segments/children',
    params: {
      query: {
        partnerId: `number`,
        providerId: `number`,
        parentId?: `number`,
        showOnlyNonZeroSegments?: `boolean`,
        showOnlyReadySegments?: `boolean`,
      }
    }
  };

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

---

Retargeted Audiences

Create Retargeted Audience

POST

Create a Retargeted Audience.

Request Schema
audienceName string	Audience name
dateCollectionBy string	Date collection can be either month or date_range
dateCollectionPeriod integer	Data collection period
startDate integer	Start date in Unix epoch milliseconds, required if dateCollectionBy is set to date_range
endDate integer	End date in Unix epoch milliseconds, required if dateCollectionBy is set to date_range

Response Properties

audienceId integer	Audience ID
tag_script string	Tag script
message string	Success message

JSON

Select exampleBy MonthBy Date Range

Request Sample

{
  "audienceName": "Test audience by month",
  "dataCollectionBy": "month",
  "dataCollectionPeriod": 1
}

Request Sample

{
  "audienceName": "Test audience by date_range",
  "dataCollectionBy": "date_range",
  "startDate": 1753262493020,
  "endDate": 1753900200000
}

Response 200

{
  "success": true,
  "data": {
    "tag_script": "<script src='https://pxl.stage.iqm.com/c/4c90b124-bfbe-4af1-b780-d2a1d3cb93c1' async></script>",
    "audienceId": 1140586,
    "message": "Test audience by month audience created successfully"
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function CreateRetargetedAudience(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/audience/retargeted',
    requestBody: {
      content: {
        "application/json": {
          audienceName: `string`,
          dateCollectionBy: `string`,
          dateCollectionPeriod: `number`,
          startDate?: `number`,
          endDate?: `number`
        }
      }
    }
  };

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

---

Update Retargeted Audience

PUT

Update a Retargeted Audience.

Path Parameter
audienceId string	Retargeted Audience ID

Request Schema
audienceName string	Audience name
dateCollectionBy string	Date collection can be either month or date_range
dateCollectionPeriod integer	Data collection period
startDate integer	Start date in Unix epoch milliseconds, required if dateCollectionBy is set to date_range
endDate integer	End date in Unix epoch milliseconds, required if dateCollectionBy is set to date_range

Response Properties

tag_script string	Tag script
message string	Success message

JSON

Select exampleBy MonthBy Date Range

Request Sample

{
  "audienceName": "Test audience by month",
  "dataCollectionBy": "month",
  "dataCollectionPeriod": 1
}

Request Sample

{
  "audienceName": "Test audience by date_range",
  "dataCollectionBy": "date_range",
  "startDate": 1753262493020,
  "endDate": 1753900200000
}

Response 200

{
  "success": true,
  "data": {
    "tag_script": "<script src='https://sample.url.com/c/02e378aa-275b-40aa-9a2c-a41ce2e02c88' async></script>",
    "message": "Your changes have been saved successfully"
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function EditRetargetAudience(): Promise<Responses> {
  const options = {
    method: 'PUT',
    url: 'https://api.iqm.com/api/v3/audience/retargeted/{audienceId}',
    param: {
      path: {
        audienceId: `string`
      }
    },
    requestBody: {
      content: {
        "application/json": {
          tag_duration: `string`,
          tag_name: `string`,
          tag_time: `number`,
        }
      }
    }
  };

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

---

Retargeted Audience Email Notification

POST

Send email with Retargeted audience Pixel code to specified recipients.

Path Parameter
audienceId string	Retargeted Audience ID

Request Schema
recipientEmails array of strings	Recipient emails

Response Properties

message string

Success message

JSON

Request Sample

{
  "recipientEmails": [
    "test.s@gmail.com"
  ]
}

Response 200

{
  "success": true,
  "data": {
    "message": "Pixel Code emailed successfully"
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json;charset=UTF-8": {
        statusCode: number;
        responseObject: {
          message: string;
        };
      };
    };
  };
}

function RetargetAudienceemailnotify(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/audience/retargeted/{audienceId}/email-notification',
    requestBody: {
      content: {
        "application/json": {
          pixelCode: `string`,
          recipients: `string`,
        }
      }
    }
  };

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

---

Geofarmed Audiences

Geofarmed Audience Details

GET

Get Geofarmed Audience Details by ID.

Path Parameter
audienceId string	Geofarmed Audience ID

Response Properties

audienceId integer	Audience ID
audienceName string	Audience name
audienceStatusId integer	Audience status ID
createdAt integer	Creation timestamp (epoch seconds)
reach integer	Audience reach
cpm number	Cost per thousand impressions
audienceSubtypeId integer	Audience Subtype ID
dataPartnerId integer	Data partner ID
dataPartnerMetrics array of objects	Data partner metrics
dataPartnerMetrics object properties id integer Data partner ID reach integer Reach for this data partner
frequency integer	The frequency of visit to the geographical location
frequencyTypeId integer	Frequency Type ID
startDate integer	Unix epoch start date (seconds)
endDate integer	Unix epoch end date (seconds)
timezoneId integer	Timezone ID
timeRange object	Time range configuration (may be null)
locations object	Locations object
locations object properties country integer Country ID included object Included locations object included object properties zipCodes array of strings Zip codes customAreas array of objects Custom areas locationIds array of integers Location IDs customAreas object properties latitude integer Latitude longitude integer Longitude radius integer Radius (miles) address string Addresses to add to custom area locationId integer Location ID polypath object A set of coordinates defining the boundary of the custom area polypath object properties lat integer Latitude lng integer Longitude isIncluded boolean Indicates if custom area is included in Geofarmed Audience: true cid string Country ID sid string State ID type string Type of custom area unit string Measurement unit for radius of area cdId integer Congressional District ID sdId integer Senate District ID hdId integer House District ID excluded object Excluded locations object excluded object properties zipCodes array of strings Zip codes customAreas array of objects Custom areas locationIds array of integers Location IDs customAreas object properties latitude integer Latitude longitude integer Longitude radius integer Radius (miles) address string Address locationId integer Location ID polypath object A set of coordinates defining the boundary of the custom area polypath object properties lat integer Latitude lng integer Longitude isIncluded boolean Indicates if custom area is included in Geofarmed Audience: true cid string Country ID sid string State ID type string Type of custom area unit string Measurement unit for radius of area cdId integer Congressional District ID sdId integer Senate District ID hdId integer House District ID locationFileIds array of integers Location file IDs
bulkLocationDetails object	Bulk location details object
bulkLocationDetails object properties fileName string File name fileType string File type validLocations array of objects Valid locations validLocations object properties latitude number Latitude longitude number Longitude radius number Radius address string Address locationId integer Location ID cid string Country ID sid string State ID cdId integer Congressional District ID sdId integer Senate District ID hdId integer House District ID isIncluded boolean Is included flag invalidLocations null Invalid locations locationRejectionReasons null Location rejection reasons campaignId null Campaign ID id integer ID rowCount null Row count invalidLocationsCount null Invalid locations count duplicateLocationsCount null Duplicate locations count

JSON

Response 200

{
  "success": true,
  "data": {
    "audienceId": 1141873,
    "audienceName": "my geo check 3",
    "audienceStatusId": 1,
    "createdAt": 1754997589,
    "reach": 14300,
    "cpm": 10,
    "audienceSubtypeId": 3,
    "dataPartnerId": 7,
    "dataPartnerMetrics": [
      {
        "id": 7,
        "reach": 14300
      },
      {
        "id": 10,
        "reach": 14142
      },
      {
        "id": 8,
        "reach": 4989
      }
    ],
    "frequency": 1,
    "frequencyTypeId": 1,
    "startDate": 1752465600,
    "endDate": 1752552000,
    "timezoneId": 29,
    "timeRange": null,
    "locations": {
      "included": {
        "zipCodes": [
          "03060"
        ],
        "customAreas": [
          {
            "latitude": 36.03264396648448,
            "longitude": -119.88024262579326,
            "radius": 0.5,
            "address": "24M9+3W Kettleman City, CA, USA",
            "locationId": 0,
            "cid": "US",
            "sid": "CA",
            "type": "circle",
            "unit": "mile",
            "cdId": 0,
            "sdId": 0,
            "hdId": 0,
            "isIncluded": true
          },
          {
            "latitude": 36.030047897646504,
            "longitude": -119.85904244573955,
            "radius": 0.5,
            "address": "24JR+29 Kettleman City, CA, USA",
            "locationId": 0,
            "cid": "US",
            "sid": "CA",
            "type": "circle",
            "unit": "mile",
            "cdId": 0,
            "sdId": 0,
            "hdId": 0,
            "isIncluded": true
          },
          {
            "latitude": 36.03107268797965,
            "longitude": -79.36266450079326,
            "radius": 31.99,
            "address": "Graham, NC 27253, USA",
            "locationId": 0,
            "polypath": [
              {
                "lat": 36.38721903107804,
                "lng": -79.62633637579326
              },
              {
                "lat": 35.53354668242086,
                "lng": -79.97789887579326
              },
              {
                "lat": 35.67646553441582,
                "lng": -78.83532075079326
              },
              {
                "lat": 36.52859869353844,
                "lng": -78.74743012579326
              }
            ],
            "cid": "US",
            "sid": "NC",
            "type": "custom",
            "unit": "mile",
            "cdId": 0,
            "sdId": 0,
            "hdId": 0,
            "isIncluded": true
          },
          {
            "latitude": 34.4534306784404,
            "longitude": -80.72496918829326,
            "radius": 20.21,
            "address": "Camden, SC 29020, USA",
            "locationId": 0,
            "polypath": [
              {
                "lat": 34.59837718611232,
                "lng": -80.41735200079326
              },
              {
                "lat": 34.59837718611232,
                "lng": -81.03258637579326
              },
              {
                "lat": 34.30848417076847,
                "lng": -81.03258637579326
              },
              {
                "lat": 34.30848417076847,
                "lng": -80.41735200079326
              }
            ],
            "cid": "US",
            "sid": "SC",
            "type": "square",
            "unit": "mile",
            "cdId": 0,
            "sdId": 0,
            "hdId": 0,
            "isIncluded": true
          }
        ],
        "locationIds": [
          1252824,
          1252825
        ]
      },
      "excluded": {
        "zipCodes": [],
        "customAreas": [],
        "locationIds": []
      },
      "locationFileIds": [
        17063
      ],
      "country": 30100001
    },
    "bulkLocationDetails": {
      "17063": {
        "fileName": "bulk-location-example.csv",
        "fileType": "location",
        "validLocations": [
          {
            "latitude": 40.7128,
            "longitude": -74.006,
            "radius": 0.5,
            "address": "230 Broadway, New York, NY 10007, USA",
            "locationId": 1252824,
            "cid": "US",
            "sid": "NY",
            "cdId": 0,
            "sdId": 0,
            "hdId": 0,
            "isIncluded": true
          },
          {
            "latitude": 36.7783,
            "longitude": -119.4179,
            "radius": 1,
            "address": "2630 Croydon Drive, Sanger, CA 93657, USA",
            "locationId": 1252825,
            "cid": "US",
            "sid": "CA",
            "cdId": 0,
            "sdId": 0,
            "hdId": 0,
            "isIncluded": true
          }
        ],
        "invalidLocations": null,
        "locationRejectionReasons": null,
        "campaignId": null,
        "id": 17063,
        "rowCount": null,
        "invalidLocationsCount": null,
        "duplicateLocationsCount": null
      }
    }
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
          success: boolean;         
          data: {             
              audienceId: number;
              audienceName: string;
              audienceStatusId: number;
              createdAt: number;
              reach: number;
              cpm: number;
              audienceSubtypeId: number;
              dataPartnerId: number;
              dataPartnerMetrics: {
                  id: number;
                  reach: number;
              }[];
              frequency: number;             
              frequencyTypeId: number;             
              startDate: number;              
              endDate: number;             
              timezoneId: number;
              timeRange: {
                  [key: string]: string;
              } | null;
              locations: {
                  included: {
                      zipCodes: string[];
                      customAreas: {
                          latitude: number;
                          longitude: number;
                          radius: number;
                          address: string;                          
                          locationId: number;
                          cid: string;
                          sid: string;
                          type: string;
                          unit: string;                         
                          cdId: number;                         
                          sdId: number;                         
                          hdId: number;
                          isIncluded: boolean;
                          polypath?: {
                              lat: number;
                              lng: number;
                          }[];
                      }[];
                      locationIds: number[];
                  };
                  excluded: {
                      zipCodes: string[];
                      customAreas: {
                          latitude: number;
                          longitude: number;
                          radius: number;
                          address: string;                         
                          locationId: number;
                          cid: string;
                          sid: string;
                          type: string;
                          unit: string;                        
                          cdId: number;                         
                          sdId: number;                         
                          hdId: number;
                          isIncluded: boolean;
                          polypath?: {
                              lat: number;
                              lng: number;
                          }[];
                      }[];
                      locationIds: number[];
                  };
                  locationFileIds: number[];                  
                  country: number;
              };
              bulkLocationDetails: {
                  [key: string]: {
                      fileName: string;
                      fileType: string;
                      validLocations: {
                          latitude: number;
                          longitude: number;
                          radius: number;
                          address: string;                        
                          locationId: number;
                          cid: string;
                          sid: string;                          
                          cdId: number;                         
                          sdId: number;                          
                          hdId: number;
                          isIncluded: boolean;
                      }[];
                      invalidLocations: null;
                      locationRejectionReasons: null;
                      campaignId: null;
                      id: number;
                      rowCount: null;
                      invalidLocationsCount: null;
                      duplicateLocationsCount: null;
                  };
              };
          };
      };
    };
  };
}

function GetGeofarmedAudienceDetails(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/geo-farmed/{audienceId}',
    params: {
      path: {
        audienceId: `string`
      }
    }
  };

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

---

Create Geofarmed Audience

POST

Create a Geofarmed Audience.

Request Schema
audienceName string	Audience name
frequency integer	The frequency of visit to the geographical location (1-10), based on frequencyTypeId
frequencyTypeId integer	Frequency Type ID
timezoneId integer	Timezone ID
startDate integer	Unix epoch start date, in milliseconds
endDate integer	Unix epoch end date, in milliseconds
timeRange object	Name-Value pairs of day of the week (e.g. Monday: 1, Tuesday: 2, etc.) and an object containing a time range (see example below this table)
timeRangeWithTimezone object	Alternative time range configuration with timezone support
audienceSubtypeIds array of integers	Audience Subtype IDs
removedLocationsIds array of integers	Removed location IDs, as specified in the uploaded location file
locations object	Locations object
locations object properties country integer Country ID included object Included locations object included object properties zipCodes array of strings Zip codes customAreas array of objects Custom areas locationIds array of integers Location IDs customAreas object properties latitude integer Latitude longitude integer Longitude radius integer Radius address string Address stateShortName string State short name countryShortName string Country short name locationId integer Location ID rejectionReason string Rejection reason (if applicable) polypath object A set of coordinates defining the boundary of the custom area polypath object properties lat integer Latitude lng integer Longitude placemarkName string Placemark name cid string Country ID sid string State ID type string Type of custom area unit string Measurement unit for radius cdId integer Congressional District ID sdId integer Senate District ID hdId integer House District ID isIncluded boolean Indicates if custom area is included in Geofarmed Audience excluded object Excluded locations object excluded object properties zipCodes array of strings Zip codes customAreas array of objects Custom areas locationIds array of integers Location IDs customAreas object properties latitude integer Latitude longitude integer Longitude radius integer Radius address string Address stateShortName string State short name countryShortName string Country short name locationId integer Location ID rejectionReason string Rejection reason (if applicable) polypath object A set of coordinates defining the boundary of the custom area polypath object properties lat integer Latitude lng integer Longitude placemarkName string Placemark name cid string Country ID sid string State ID type string Type of custom area unit string Measurement unit for radius cdId integer Congressional District ID sdId integer Senate District ID hdId integer House District ID isIncluded boolean Indicates if custom area is excluded from Geofarmed Audience locationFileIds array of integers Location file IDs

timeRange example

"timeRange": {
  "0": [
    [
      "19:00:00",
      "22:00:00"
    ]
  ],
  "1": [
    [
      "09:00:00",
      "12:00:00"
    ],
    [
      "15:00:00",
      "18:00:00"
    ]
  ],
  "2": [
    [
      "04:00:00",
      "11:00:00"
    ]
  ],
  "4": [
    [
      "06:00:00",
      "12:00:00"
    ]
  ],
  "6": [
    [
      "01:00:00",
      "10:00:00"
    ]
  ]
},

Response Properties

id integer	Audience ID
message string	Success message

JSON

Request Sample

{
  "audienceName": "Healthcare Professionals NYC",
  "frequency": 5,
  "frequencyTypeId": 2,
  "startDate": 1697040000,
  "endDate": 1699641600,
  "timezoneId": 1,
  "audienceSubtypeIds": [
    3,
    4
  ],
  "timeRange": {
    "0": [
      [
        "09:00:00",
        "17:00:00"
      ]
    ],
    "1": [
      [
        "10:00:00",
        "18:00:00"
      ]
    ]
  },
  "locations": {
    "country": 1,
    "included": {
      "zipCodes": [
        "10001",
        "10002",
        "10003"
      ],
      "customAreas": [
        {
          "type": "circle",
          "latitude": 40.7128,
          "longitude": -74.006,
          "radius": 5,
          "unit": "mile"
        }
      ]
    },
    "locationFileIds": [
      123
    ]
  }
}

Response 200

{
  "success": true,
  "data": {
    "audienceIds": [
      1142280
    ],
    "message": "Test_aud audience created successfully"
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function CreateGeofarmedAudience(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/audience/geo-farmed/add',
    requestBody: {
      content: {
        "application/json": {
          audienceName: `string`,
          frequency: `number`,
          frequencyType: `number`,
          startDate: `number`,
          endDate: `number`,
          timezone: `number`,
          timeRange: {
            [key: string]: `string`,
          },
          removedLocationsIds: `number[]`,
          locations: {
            country: `number`,
            included: {
              locationIds: `number[]`,
              states: `number[]`,
              counties: `number[]`,
              cities: `number[]`,
              stateSenates: `number[]`,
              stateHouses: `number[]`,
              congressionalDistricts: `number[]`,
              zipCodes: `number[]`,
              customAreas: {
                latitude: `number`,
                longitude: `number`,
                radius: `number`,
                address: `string`,
                locationId: `number`,
                isIncluded: `boolean`,
                cid: `string`,
                sid: `string`,
                type: `string`,
                unit: `string`,
                cdId: `number`,
                sdId: `number`,
                hdId: `number`,
                polypath?: {
                  lat: `number`,
                  lng: `number`,
                }[],
              }[],
            },
            excluded: {
              locationIds: `number[]`,
              cities: `number[]`,
              counties: `number[]`,
              stateSenates: `number[]`,
              stateHouses: `number[]`,
              congressionalDistricts: `number[]`,
              zipCodes: `number[]`,
              customAreas: {
                latitude: `number`,
                longitude: `number`,
                radius: `number`,
                address: `string`,
                locationId: `number`,
                isIncluded: `boolean`,
                cid: `string`,
                sid: `string`,
                type: `string`,
                unit: `string`,
                cdId: `number`,
                sdId: `number`,
                hdId: `number`,
                polypath?: {
                  lat: `number`,
                  lng: `number`,
                }[],
              }[],
            },
            locationFileIds: number[],
          }
        }
      }
    }
  };

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

Contextual Audiences

Contextual Audience Details

GET

Get Contextual Audience details by ID.

Path Parameter
audienceId string	Audience ID

Response Properties

audienceId integer	Audience ID
audienceName string	Audience name
audienceStatusId integer	Audience status ID
cpm number	Cost per thousand impressions
reach integer	Audience reach
createdAt integer	Unix epoch creation date (milliseconds)
keywords array of strings	Keywords
urls array of strings	URLs
dataCollectionMethodId integer	Data collection method ID
dataCollectionDays integer	Data collection days
frequency integer	Frequency
dataPartnerId integer	Data partner ID
dataPartnerMetrics array of objects	Data partner metrics
dataPartnerMetrics object properties id integer Data partner ID reach integer Reach for this data partner

JSON

Response 200

{
  "success": true,
  "data": {
    "audienceId": 1141259,
    "audienceName": "Test_aud_contextual",
    "audienceStatusId": 8,
    "cpm": 1.5,
    "reach": 0,
    "createdAt": 1753773402000,
    "keywords": [
      "Test"
    ],
    "urls": [
      "http://iqm.com"
    ],
    "dataCollectionMethodId": 2,
    "dataCollectionDays": 10,
    "frequency": 5,
    "dataPartnerId": 1,
    "dataPartnerMetrics": [
      {
        "id": 1,
        "reach": 1000
      },
      {
        "id": 2,
        "reach": 1000
      }
    ]
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
         audienceId: number;
         audienceName: string;
         audienceStatusId: number;
         cpm: number;
         reach: number;
         createdAt: number;
         keywords: string[];
         urls: string[];
         dataCollectionMethodId: number;
         dataCollectionDays: number;
         frequency: number;
         dataPartnerId: number;
         dataPartnerMetrics: {
           id: number;
           reach: number;
         }[];
        };
      };
    };
  };
}

function getContextualAudience(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/contextual/{audienceId}',
    params: {
      path: {
        audienceId: `number`
      }
    }
  };

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

---

Create Contextual Audience

POST

Create a Contextual Audience.

Data Collection Period: Timeframe during which a user visits the publisher(s) relevant to one or more keywords or URLs added to the contextual Audience.

info

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

The period between the start date and the end date cannot exceed 30 days.

Request Schema
audienceName string	Audience name
keywords array of strings	Keywords to generate 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 array of strings	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: 30)
audienceSubTypes integer	List of Audience Subtype IDs to further define the Contextual Audience

Response Properties

audienceIds array of integers	Audience IDs
message string	Success message

JSON

Request Sample

{
  "audienceName": "Test_aud",
  "frequency": 5,
  "startDate": 1750737600000,
  "endDate": 1753329599000,
  "keywords": [
    "Test"
  ],
  "urls": [
    "http://iqm.com"
  ],
  "timezoneId": 29,
  "dataCollectionMethodId": 1,
  "audienceSubtypes": [
    2,
    3
  ]
}

Response 200

{
  "success": true,
  "data": {
    "audienceIds": [
      1142280
    ],
    "message": "Test_aud audience created successfully"
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function createContextualAudiences(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/audience/contextual',
    requestBody: {
      content: {
        "application/json": {
          audienceName: `string`,
          keywords?: `string[]`,
          urls?: `string[]`,
          frequency?: `number`,
          startDate?: `number`,
          endDate?: `number`,
          timezoneId?: `number`,
          dataCollectionMethodId: `number`,
          dataCollectionDays?: `number`,
          audienceSubtypes?: `number[]`
        }
      }
    }
  };

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

---

Validate URL for Contextual Audience

POST

Validate given URLs to be targeted in a Contextual Audience.

Request Schema
URLs array of strings	URLs to validate

Response Properties

success boolean	Indicates Report was succesfully created: true
data array of strings	Validated URLs

JSON

Request Sample

[
  "https://sample-url-1.com",
  "https://sample-url-2.com",
  "https://sample-url-3.com"
]

Response 200

{
  "success": true,
  "data": {
    "https://sample-url-1.com": false,
    "https://sample-url-2.me": true,
    "https://sample-url-3.me": null,
    "https://sample-url-4.com": true
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function validateContextualUrl(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/audience/contextual/programmatic/url/validate',
    requestBody: {
      content: {
        "application/json": `string[]`
      }
    }
  };

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

Lookalike Audiences

Get Lookalike Audience Details

GET

Get Lookalike Audience details.

Path Parameter
audienceId string	Lookalike Audience ID

Query Parameter
isTargetingInfoRequired boolean	Includes targeting info in response (true) and targeted Campaign details (type of targeting, attached Campaign status), default: (false)

Response Properties

audienceId integer	Audience ID
audienceName string	Audience name
audienceStatusId integer	Audience status ID
createdAt integer	Creation timestamp (epoch seconds)
organizationName string	Organization name
owId integer	Organization Workspace ID
createdByUowId integer	Created by User Organization Workspace ID
createdByUser string	Created by user name
createdByUserEmail string	Created by user email (may be null)
reach integer	Audience reach
cpm number	Cost per thousand impressions
sourceAudienceIds array of integers	Source audience IDs
geoLocationDetails object	Geo location details
geoLocationDetails object properties countryIds array of integers Country IDs stateIds array of integers State IDs cityIds array of integers City IDs countyIds array of integers County IDs senateDistrictIds array of integers Senate District IDs houseDistrictIds array of integers House District IDs congressionalDistrictIds array of integers Congressional District IDs
audienceSize integer	Audience size
targetedCampaignList array of objects	Targeted campaign list
targetedCampaignList object properties campaignName string Campaign name campaignId integer Campaign ID targetingTypeId integer Targeting type ID (1=Whitelist, 2=Blacklist) campaignStatus string Campaign status
approvedRejectedByUserName string	Approved/rejected by user name (may be null)
rejectionReason string	Rejection reason (may be null)
isApprovalAccess boolean	Indicates if user has approval access

Response 200

{
  "success": true,
  "data": {
    "audienceId": 1141499,
    "audienceName": "Test lookalike Audience - 90K",
    "audienceStatusId": 3,
    "createdAt": 1753882035,
    "organizationName": "Political Advertiser - Audience Bidder",
    "owId": 204472,
    "createdByUowId": 267663,
    "createdByUser": "Political Advertiser - Audience Bidder",
    "createdByUserEmail": null,
    "reach": 2000,
    "cpm": 1.5,
    "sourceAudienceIds": [123456, 123457],
    "geoLocationDetails": {
      "countryIds": [30100001],
      "stateIds": [30200001, 30200002, 30200003, 30200004],
      "cityIds": [30400001, 30400002],
      "countyIds": [30300001, 30300003],
      "senateDistrictIds": [687, 688],
      "houseDistrictIds": [5098, 5121],
      "congressionalDistrictIds": [350, 78]
    },
    "audienceSize": 10,
    "targetedCampaignList": [
      {
        "campaignName": "Audience - LookAlike Audience with IP Based",
        "campaignId": 565213,
        "targetingTypeId": 1,
        "campaignStatus": "Running"
      },
      {
        "campaignName": "Audience - LookAlike Audience with Device Based - Blacklisted",
        "campaignId": 565262,
        "targetingTypeId": 2,
        "campaignStatus": "Paused"
      }
    ],
    "approvedRejectedByUserName": null,
    "rejectionReason": null,
    "isApprovalAccess": true
  }
}

---

Create Lookalike Audience

POST

Create a Lookalike Audience.

Request Schema
audienceName string	Audience name
sourceAudienceIds string	Source Audience IDs
countryIds string	Country IDs
stateIds string	State IDs
cityIds string	City IDs
countyIds string	County IDs
senateDistrictIds string	Senate District IDs
houseDistrictIds string	House District IDs
congressionalDistrictIds string	Congressional District IDs
audienceSize integer	Audience size

Response Properties

audienceId integer	Audience ID
message string	Success message

JSON

Select exampleMinimal Location Fields SampleAll Location Fields Sample

Request Sample

{
  "audienceName": "Test Lookalike Audience",
  "sourceAudienceIds": "12345,67890",
  "audienceSize": 5,
  "countryIds": "1",
  "stateIds": "10,20,30"
}

Request Sample

{
  "audienceName": "Test Lookalike Audience with Full Geo",
  "sourceAudienceIds": "12345",
  "audienceSize": 3,
  "countryIds": "1",
  "stateIds": "10,20",
  "cityIds": "100,200,300",
  "countyIds": "50,60",
  "senateDistrictIds": "1,2,3",
  "houseDistrictIds": "10,20",
  "congressionalDistrictIds": "5,6,7"
}

Response 200

{
  "success": true,
  "data": {
    "audienceId": 1140586,
    "message": "Test Lookalike Audience audience created successfully"
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function CreateLookalikeAudience(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/audience/lookalike',
    requestBody: {
      content: {
        "application/json": {
          audienceName: `string`,
          sourceAudienceIds: `string`,
          countryIds: `string`,
          stateIds: `string`,
          cityIds: `string`,
          countyIds: `string`,
          senateDistrictIds: `string`,
          houseDistrictIds: `string`,
          congressionalDistrictIds: `string`,
          audienceSize: `number`,
        }
      }
    }
  };

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

Campaign Audiences

Campaign Audience Details

GET

Get Campaign Audience details by ID.

Path Parameter
campaign_audience_id string	Campaign Audience ID

Response Properties

audienceId integer	Audience ID
audienceName string	Audience name
audienceStatusId integer	Audience status ID
cpm number	Cost per thousand impressions
uniques integer	Count of unique Audiences reached
createdAt integer	Unix epoch creation date (milliseconds)
campaignDetails object	Campaign details
campaignDetails object properties impressions array of integers Impressions array clicks array Clicks array conversions array Conversions array
startDate integer	Unix epoch start date (milliseconds)
endDate integer	Unix epoch end date (milliseconds)

JSON

Response 200

{
  "success": true,
  "data": {
    "audienceId": 119431,
    "audienceName": "asdf",
    "audienceStatusId": 1,
    "cpm": 2.5,
    "uniques": 56590,
    "createdAt": 1740876000000,
    "campaignDetails": {
      "clicks": [],
      "conversions": [],
      "impressions": [
        56590
      ]
    },
    "startDate": 1740816000000,
    "endDate": 1753167600000
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          audienceId: number;
          audienceName: string;
          audienceStatusId: number;
          cpm: number;
          uniques: number;
          createdAt: number;
          campaignDetails: {
            clicks: any[];
            conversions: any[];
            impressions: number[];
          };
          startDate: number;
          endDate: number;
        };
      };
    };
  };
}

function GetCampaignAudienceDetails(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/campaign/{campaign_audience_Id}',
    params: {
      path: {
        campaign_audience_Id: `string`
      }
    }
  };

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

---

Create Campaign Audience

POST

Create a Campaign Audience.

Request Schema
audienceName string	Audience name
startDate integer	Unix epoch start date, in milliseconds
endDate integer	Unix epoch end date, in milliseconds
campaignDetails object	Campaign details
campaignDetail object properties impressions array of integers Impressions clicks array of integers Clicks conversions array of integers Conversions

Response Properties

audienceId integer	Audience ID
message string	Success message

JSON

Request Sample

{
  "audienceName": "Sample audience name",
  "startDate": 1638316800,
  "endDate": 1640085173,
  "campaignDetails": {
    "impressions": [
      1,
      2
    ],
    "clicks": [
      3
    ],
    "conversions": [
      4
    ]
  }
}

Response 200

{
  "success": true,
  "data": {
    "audienceId": 1140606,
    "message": "Test campaign audience audience created successfully"
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function CreateCampaignAudience(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/audience/campaign/add',
    requestBody: {
      content: {
        "application/json": {
          audienceName: `string`,
          startDate: `number`,
          endDate: `number`,
          campaignDetail: {
            impressions: `number[]`,
            clicks: `number[]`,
            conversions: `number[]`,
          }
        }
      }
    }
  };

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

---

Get Campaign Audience History

POST

Get the Audience history details for specified Campaigns.

Request Schema
campaignId array of integers	Campaign IDs
subTypeIds array of integers	Audience Subtype IDs
historicalData boolean	Fetches historical data (true) or current data (false)
typeIds array of integers	Audience Type IDs
noOfEntries integer	Number of entries per page
pageNo integer	Page number of retrieved data

Response Properties

totalRecords integer	Total records count
filteredRecords integer	Filtered records count
audienceDetails array of objects	Audience details array
audienceDetails object properties id integer Audience ID campaignIds array of integers Campaign IDs name string Audience name audienceSubTypeId integer Audience subtype ID (may be null) typeId integer Audience type ID

Request Sample

{
  "campaignId": [
    540050
  ],
  "subTypeIds": [],
  "historicalData": false,
  "typeIds": [],
  "noOfEntries": 2,
  "pageNo": 1
}

Response 200

{
  "success": true,
  "data": {
    "totalRecords": 12,
    "filteredRecords": 12,
    "audienceDetails": [
      {
        "id": 1023234,
        "campaignIds": [
          540050
        ],
        "name": "MA-1 voter id",
        "audienceSubTypeId": null,
        "typeId": 1
      },
      {
        "id": 1054138,
        "campaignIds": [
          540050
        ],
        "name": "MA With 90 K Records And 8 Columns NYSD 3 Digital Universe Csv",
        "audienceSubTypeId": null,
        "typeId": 1
      }
    ]
  }
}

Pre-bid Audiences

Pre-bid Audience Details

GET

Get Pre-bid Audience details by ID.

Path Parameter
audienceId string	Pre-bid Audience ID

Response Properties

audienceId integer	Audience ID
audienceName string	Audience name
owId integer	Organization Workspace ID
createdByUowId integer	Created by User Organization Workspace ID
cpm integer	Cost per mille
createdAt integer	Unix epoch creation date, in milliseconds
prebidSegmentDetails array of objects	Pre-bid Segment Details
prebidSegmentDetails object properties prebidSegmentId integer Pre-bid Audience Segment ID prebidSegmentName string Pre-bid Audience Segment name prebidRootId integer Pre-bid Audience Segment root ID description string Description parentPathKey string Key representing parent path or category that an Audience Segment belongs to cpm integer Cost per mille creativeTypeIds array of integers Creative Type ID list leaf boolean Indicates that an Audience Segment is a leaf node in a hierarchical Audience structure: true providerId integer Provider ID providerLogoUrl string Provider logo URL

JSON

Response 200

{
  "success": true,
  "data": {
    "audienceId": 1139208,
    "audienceName": "test",
    "cpm": 0.325,
    "owId": 201427,
    "createdByUowId": 9480,
    "createdAt": 1750866960,
    "prebidSegmentDetails": [
      {
        "prebidSegmentId": 247,
        "prebidSegmentName": "Impressions with Insufficient IAB Viewability Data",
        "description": "Impressions where DV does not have sufficient viewability performance statistics for the URL or URL can not be targeted (e.g., blinded).",
        "parentPathKey": "Viewability > Video",
        "prebidRootId": 159,
        "cpm": 0.2,
        "creativeTypeIds": [
          14,
          15
        ],
        "leaf": false,
        "providerId": 2,
        "providerLogoUrl": "https://d2v0lj9tfbnmhu.cloudfront.net/assets/dist/audience/prebid-providers/DV-logo.svg"
      },
      {
        "prebidSegmentId": 248,
        "prebidSegmentName": "80% or Higher Viewability Rate",
        "description": "For video, this is a rate-based segment used to target the URLs that have historically achieved a 80% or higher viewability rate based on the IAB standard.",
        "parentPathKey": "Viewability > Video",
        "prebidRootId": 159,
        "cpm": 0.2,
        "creativeTypeIds": [
          14,
          15
        ],
        "leaf": false,
        "providerId": 2,
        "providerLogoUrl": "https://d2v0lj9tfbnmhu.cloudfront.net/assets/dist/audience/prebid-providers/DV-logo.svg"
      }
    ]
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          id: number;
          name: string;
          status: string;
          owId: number;
          createdByUowId: number;
          cpm: number;
          createdOn: number;
          prebidSegmentData: {
            prebidAudienceSegmentId: number;
            prebidAudienceSegmentName: string;
            prebidAudienceSegmentRootId: number;
            description: string;
            parentPathKey: string;
            cpm: number;
            creativeTypeIdList: number[];
            providerId: number;
            providerName: string;
            providerLogoUrl: string;
          }[];
        };
      };
    };
  };
}

function getPrebidAudienceDetailsByAudienceId(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/prebid/{prebidAudienceId}',
    params: {
      path: {
        prebidAudienceId: `string`
      }
    }
  };

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

---

Search Pre-bid Audience Details

POST

Search Pre-bid Audiences by specified parameters.

Request Schema
searchField string	Filter results by search field
prebidSegmentIds array of integers	Pre-bid Segment ID list
customerOwId integer	Customer Organization Workspace ID
showinActiveSegments boolean	Include inactive segments in results: true to include inactive segments; false to exclude inactive segments (default: false)

Response Properties

prebidSegmentData array of objects	Pre-bid Segment Data
prebidSegmentData object properties prebidSegmentId integer Pre-bid Audience Segment ID prebidSegmentName string Pre-bid Audience Segment name description string Description parentPathKey string Parent path key cpm integer Cost per mille isLeaf boolean Indicates that an Audience Segment is a leaf node in a hierarchical Audience structure: true creativeTypeIds array of integers Creative Type ID list prebidRootId integer Pre-bid Audience Root ID providerId integer Provider ID

JSON

Select exampleAdvertiser Request SampleNon-Advertiser Request Sample

Request Sample

{
  "prebidSegmentIds": [
    156,
    157
  ],
  "searchField": "risk",
  "showInActiveSegments": true
}

Request Sample

{
  "prebidSegmentIds": [
    156,
    157
  ],
  "searchField": "risk",
  "customerOwId": 201332
}

Response 200

{
  "success": true,
  "data": [
    {
      "prebidSegmentId": 158,
      "prebidSegmentName": "Avoid High and Moderate risk Alcohol content pages",
      "description": "Avoid High and Moderate risk Alcohol content pages",
      "parentPathKey": "Brand Safety > Display",
      "cpm": 0.05,
      "isLeaf": true,
      "creativeTypeIds": [
        11,
        14
      ],
      "prebidRootId": 1,
      "providerId": 1
    },
    {
      "prebidSegmentId": 156,
      "prebidSegmentName": "Avoid High and Moderate risk Adult content pages",
      "description": "Avoid High and Moderate risk Adult content pages",
      "parentPathKey": "Brand Safety > Display",
      "cpm": 0.05,
      "isLeaf": true,
      "creativeTypeIds": [
        11,
        14
      ],
      "prebidRootId": 1,
      "providerId": 1
    }
  ]
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        success: boolean;
        data: {
          totalRecords: number;
          filteredRecords: number;
          prebidSegmentData: {
            prebidAudienceSegmentId: number;
            prebidAudienceSegmentName: string;
            prebidAudienceSegmentRootId: number;
            description: string;
            parentPathKey: string;
            cpm: number;
            creativeTypeIdList: number[];
            providerId: number;
            providerName: string;
            providerLogoUrl: string;
          }[];
        };
      };
    };
  };
}

function getPrebidSegmentDetailsBySearch(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/audience/prebid/details/search/list',
    requestBody: {
      content: {
        "application/json": {
          providerIdList?: `number[]`,
          prebidAudienceSegmentIdList?: `number[]`,
          prebidAudienceIdList?: `number[]`,
          searchField?: `string`
        }
      }
    }
  };

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

---

Create Pre-bid Audience

POST

Pre-bid Audiences are groups of Fraud , Brand Safety, and Viewability pre-bid segments that you select. You can create these audiences and seamlessly integrate them into new or existing Campaigns.

warning

The IQM platform supports one Creative type per Campaign. Pre-bid segments include both display and video that can be selected. Choose only one format for each Pre-bid Audience to avoid incurring extra charges.

Request Schema
audienceName string	Pre-bid Audience name
prebidSegmentIds array of integers	Pre-bid Audience Segment ID list
prebidProviderId integer	Pre-bid Audience Provider ID

Response Properties

id integer	Audience ID
message string	Success message

JSON

Request Sample

{
  "audienceName": "string",
  "prebidSegmentIds": [
    0
  ],
  "prebidProviderId": 1
}

Response 200

{
  "success": true,
  "data": {
    "audienceId": 1026631,
    "message": "Test Audience audience created successfully"
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function createPrebidAudience(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/audience/prebid',
    requestBody: {
      content: {
        "application/json": {
          audienceName: `string`,
          prebidSegmentIds: `number[]`,
          prebidProviderId: `number`
        }
      }
    }
  };

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

---

Update Pre-bid Audience

PATCH

Update a Pre-bid Audience.

Path Parameter
audienceId string	Pre-bid Audience ID

Request Schema
audienceName string	Pre-bid Audience Name
prebidSegmentIds array of integers	Pre-bid Audience Segment ID list
prebidProviderId integer	Pre-bid Audience Provider ID

Response Properties

audienceId integer	Audience ID
message string	Success message

JSON

Request Sample

{
  "audienceName": "Test 2",
  "prebidSegmentIds": [
    163,
    164
  ],
  "prebidProviderId": 2
}

Response 200

{
  "success": true,
  "data": {
    "audienceId": 1140257,
    "message": "Changes saved successfully"
  }
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function editPrebidAudience(): Promise<Responses> {
  const options = {
    method: 'PATCH',
    url: 'https://api.iqm.com/api/v3/audience/prebid/{audienceId}',
    params: {
      path: {
        audienceId: `number`,
      }
    },
    requestBody: {
      content: {
        "application/json": {
          audienceName: `string`,
          prebidSegmentIds: `number[]`,
          prebidProviderId: `number`
        }
      }
    }
  };

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

---

Get Pre-bid Provider Child Segment Details

GET

Get the Pre-bid Provider Child Segment Details.

Query Parameter
showinActiveSegments boolean	Include inactive segments in results: true to include inactive segments; false to exclude inactive segments (default: false)

Response Properties

providerId integer	Provider ID
providerName string	Provider name
description string	Provider description
providerLogoUrl string	Provider logo URL
childSegments array of objects	Child segments details
childSegments object properties prebidSegmentId integer Pre-bid Segment ID prebidSegmentName string Pre-bid Segment name description string Pre-bid Segment description parentPathKey string Parent path key cpm number Cost per mille creativeTypeIdList array of integers Creative Type ID list leaf boolean Indicates that an Audience Segment is a leaf node in a hierarchical Audience structure: true

Response 200

{
  "success": true,
  "data": [
    {
      "providerId": 1,
      "providerName": "Integral Ad Science",
      "description": "Segments for Brand Safety, Viewability, Fraud & IVT",
      "providerLogoUrl": "http://logoUrl.com",
      "childSegments": [
        {
          "prebidSegmentId": 2,
          "prebidSegmentName": "Fraud & IVT",
          "description": "prebidSegmentDescription",
          "parentPathKey": "prebid > IAS",
          "cpm": 0,
          "creativeTypeIdList": [
            11,
            14
          ],
          "leaf": false
        },
        {
          "prebidSegmentId": 1,
          "prebidSegmentName": "Brand Safety",
          "description": "prebidSegmentDescription",
          "parentPathKey": "prebid > IAS",
          "cpm": 0,
          "creativeTypeIdList": [
            11,
            14
          ],
          "leaf": false
        }
      ]
    }
  ]
}

---

Get Pre-bid Child Segment Details

GET

Get the Pre-bid Child Segment details based on the parent Pre-bid Segment ID.

Query Parameter
prebidParentSegmentId integer	Parent Pre-bid Segment ID

Response Properties

prebidSegmentId integer	Pre-bid Segment ID
prebidSegmentName string	Pre-bid Segment name
description string	Description
parentPathKey string	Parent path key
cpm number	Cost per mille
creativeTypeIds array of integers	Creative Type ID list
leaf boolean	Indicates that an Audience Segment is a leaf node in a hierarchical Audience structure: true

Response 200

{
  "success": true,
  "data": [
    {
      "prebidSegmentId": 4,
      "prebidSegmentName": "Display",
      "description": null,
      "parentPathKey": "IAS > Brand Safety",
      "cpm": 0,
      "creativeTypeIds": [
        11,
        14
      ],
      "leaf": false
    },
    {
      "prebidSegmentId": 5,
      "prebidSegmentName": "Video",
      "description": null,
      "parentPathKey": "IAS > Brand Safety",
      "cpm": 0,
      "creativeTypeIds": [
        11,
        14
      ],
      "leaf": false
    }
  ]
}

---

DoubleVerify Pre-bid Audience Segment Details

GET

Get the DoubleVerify IVT Pre-bid Audience Segments which are free and available to an Advertiser.

Response Properties

prebidSegmentId integer	Pre-bid Segment ID
providerId integer	Provider ID
defaultSelected boolean	Indicates if segment is selected by default

JSON

Response 200

{
  "success": true,
  "data": [
    {
      "prebidSegmentId": 234,
      "providerId": 2,
      "defaultSelected": true
    },
    {
      "prebidSegmentId": 235,
      "providerId": 2,
      "defaultSelected": true
    },
    {
      "prebidSegmentId": 236,
      "providerId": 2,
      "defaultSelected": true
    }
  ]
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    headers: {
      [name: string]: unknown;
    };
    content: {
      "application/json": {
        success: boolean;
        data: {
          prebidSegmentId: number;
          providerId: number;
          defaultSelected: boolean;
        }[];
      }
    }
  };
}

function getDvIvtFreePrebidSegments(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/prebid/dv-ivt/free-segments',
  };

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

---

More Audience Details

Reach Range List for Segmented Audiences

GET

Get a static list of the available reach range used to filter Segmented Audience data.

Response Properties

id integer	Reach range ID
name string	Reach range name
displayName string	Reach range display name
order integer	order

JSON

Response 200

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "Unknown",
      "order": 1,
      "displayName": "Unknown"
    },
    {
      "id": 2,
      "name": "<10K",
      "order": 2,
      "displayName": "<10K"
    },
    {
      "id": 3,
      "name": "10K to 100K",
      "order": 3,
      "displayName": "10K to 100K"
    },
    {
      "id": 4,
      "name": "100K to 1M",
      "order": 4,
      "displayName": "100K to 1M"
    },
    {
      "id": 5,
      "name": "1M+",
      "order": 5,
      "displayName": "1M+"
    }
  ]
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json;charset=UTF-8": {
        success: boolean;
        data: {
          displayName: string;
          id: number;
          order: string;
        }[];
      };
    };
  };
}

function getSegmentReachRange(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/static/segment/reach-range',
  };

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

---

Price Range List for Segmented Audiences

GET

Get a static list of available CPM ranges used to filter Segmented Audience data.

Response Properties

id integer	Price range ID
name string	Price range name
displayName string	Price range display name
order integer	order

JSON

Response 200

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "$0 to $1",
      "order": 1,
      "displayName": "$0 to $1"
    },
    {
      "id": 2,
      "name": "$1 to $2",
      "order": 2,
      "displayName": "$1 to $2"
    },
    {
      "id": 3,
      "name": "$2 to $5",
      "order": 3,
      "displayName": "$2 to $5"
    },
    {
      "id": 4,
      "name": "$5 to $10",
      "order": 4,
      "displayName": "$5 to $10"
    },
    {
      "id": 5,
      "name": "$10+",
      "order": 5,
      "displayName": "$10+"
    }
  ]
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json;charset=UTF-8": {
        success: boolean;
        data: {
          displayName: string;
          id: number;
          order: string;
        }[];
      };
    };
  };
}

function getSegmentPriceRange(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/static/segment/price-range',
  };

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

---

Audience Type List

GET

Get a static list of Audience types.

Response Properties

id integer	Audience type ID
name string	Audience type name
displayName string	Audience type display name
displayOrder integer	Order

JSON

Response 200

{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "Matched Audience",
            "order": 1,
            "displayName": "Matched Audience"
        },
        {
            "id": 2,
            "name": "Segmented Audience",
            "order": 2,
            "displayName": "Segmented Audience"
        },
        {
            "id": 10,
            "name": "Custom Voter Audience",
            "order": 3,
            "displayName": "Custom Voter Audience"
        },
        {
            "id": 3,
            "name": "Retargeted Audience",
            "order": 4,
            "displayName": "Retargeted Audience"
        },
        {
            "id": 4,
            "name": "Geofarmed Audience",
            "order": 5,
            "displayName": "Geofarmed Audience"
        },
        {
            "id": 5,
            "name": "Contextual Audience",
            "order": 6,
            "displayName": "Contextual Audience"
        },
        {
            "id": 6,
            "name": "Lookalike Audience",
            "order": 7,
            "displayName": "Lookalike Audience"
        },
        {
            "id": 7,
            "name": "Campaign Audience",
            "order": 8,
            "displayName": "Campaign Audience"
        },
        {
            "id": 8,
            "name": "Pre-bid Audience",
            "order": 9,
            "displayName": "Pre-bid Audience"
        }
    ]
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

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

function getAudienceTypesList(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/static/audience-types',
  }

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

---

Audience Subtype List

GET

Get a static list of Audience subtypes.

Query Parameter
audienceTypeIds integer	Audience Type IDs
verticalId integer	Vertical ID

Response Properties

id integer	Audience subtype ID
name string	Audience subtype name
order integer	Order
displayName string	Audience subtype display name

Response 200

{
  "success": true,
  "data": {
    "audienceSubtypes": [
      {
        "id": 3,
        "name": "hcp",
        "order": 3,
        "displayName": "HCP"
      },
      {
        "id": 4,
        "name": "npi_nurse",
        "order": 4,
        "displayName": "Nurse"
      },
      {
        "id": 5,
        "name": "non_npi_nurse",
        "order": 5,
        "displayName": "Non-NPI Nurse"
      },
      {
        "id": 6,
        "name": "patient",
        "order": 6,
        "displayName": "Patient"
      }
    ],
    "totalRecords": 4,
    "filteredRecords": 4
  }
}

---

Audience Status List

GET

Get a static list of Audience statuses.

Query Parameter
audienceTypeIds integer	Audience Type IDs

Response Properties

id integer	Audience status ID
name string	Status name
order integer	Order
displayName string	Audience status display name

JSON

Response 200

{
  "success": true,
  "data": [
    {
      "id": 6,
      "name": "failed",
      "order": 1,
      "displayName": "Failed"
    },
    {
      "id": 2,
      "name": "pending",
      "order": 2,
      "displayName": "Pending"
    },
    {
      "id": 1,
      "name": "processing",
      "order": 3,
      "displayName": "Processing"
    },
    {
      "id": 7,
      "name": "fetching data",
      "order": 4,
      "displayName": "Fetching Data"
    },
    {
      "id": 8,
      "name": "data fetched",
      "order": 5,
      "displayName": "Data Fetched"
    },
    {
      "id": 4,
      "name": "rejected",
      "order": 6,
      "displayName": "Rejected"
    },
    {
      "id": 3,
      "name": "ready",
      "order": 7,
      "displayName": "Ready"
    }
]
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        statusCode: number;
        responseObject: {
          id: number;
          name: string;
          order: number;
          displayName: string;
        }[];
      };
    };
  };
}

function GetAudienceStatus(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/static/audience-status',
    params: {
      query: {
        audienceTypeIds: `number`
      }
    }
  };

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

---

Frequency Type List

GET

Get a static list of Geofarmed Audience frequency types.

Response Properties

id integer	Frequency ID
name string	Frequency name
displayName string	Frequency display name
order integer	Order

JSON

Response 200

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "total",
      "displayName": "Total",
      "order": 1
    },
    {
      "id": 2,
      "name": "weekly",
      "displayName": "Weekly",
      "order": 2
    },
    {
      "id": 3,
      "name": "monthly",
      "displayName": "Monthly",
      "order": 3
    }
  ]
}

TypeScript

See TypeScript Prerequisites for usage.

import {
  getInstance
} from "prerequisites"

const axios = getInstance();

interface Responses {
  200: {
    content: {
      "application/json": {
        statusCode: number;
        responseObject: {
          id: number;
          status: string;
          displayName: string;
        }[];
      };
    };
  };
}

function GetGeofarmedFrequencyTypes(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/static/frequency-type',
  };

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

---