Audience API

The Audience API allows you to create Segmented audiences for Political campaigns.

The following table describes some of the audience types:

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 Segmented audience.
Geofarmed audience	Define an audience by a custom geographical area.
Segmented audience	Group users by common characteristics to reach specific target audiences.
Contextual audience	IQM adds users to an audience when they visit sites featuring specified keywords or URLs.
Custom Voter audience	Create audiences based on voter segments which are defined by a combination of demographic, psychographic, and behavioral attributes.
Power Segment audience	Combine Power Segments using an equation to build a custom audience from curated personality and affinity segments.

More resources

• Audience targeting and data management Help Center article
• Audience API guidelines

Authentication

Use the following header parameters for all requests:

Headers
Authentication string required	Authentication bearer token See Sign up and authenticate
X-IAA-OW-ID integer required	Organization Workspace ID header

Audience details

Audience details list

POST

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. +Supported values 1 Matched audience 2 Segmented audience 3 Retargeted audience 4 Geofarmed audience 5 Contextual audience 6 Lookalike audience 7 Campaign audience 8 Pre-bid audience 9 Account Based Marketing (ABM) audience 10 Custom Voter audience (CVA) 11 Integrated Care Team (ICT) audience 12 Power Segment audience
audienceSubtypeIds array of integers	Audience subtype IDs to filter by. +Supported values 1 Practitioner 2 D2C 3 HCP 4 NPI nurse 5 Non-NPI nurse 6 Patient
owIds array of integers	Organization Workspace IDs to filter by.
audienceStatusIds array of integers	Audience status IDs to filter by. +Supported values 1 Processing 2 Pending 3 Ready 4 Rejected 5 Deleted 6 Failed 7 Fetching data 8 Data fetched
includeGenericAudience boolean	Include generic audiences.
audienceTypeIdsWithAllSubtypes array of integers	Audience type IDs to include all subtypes. +Supported values 1 Matched audience 2 Segmented audience 3 Retargeted audience 4 Geofarmed audience 5 Contextual audience 6 Lookalike audience 7 Campaign audience 8 Pre-bid audience 9 Account Based Marketing (ABM) audience 10 Custom Voter audience (CVA) 11 Integrated Care Team (ICT) audience 12 Power Segment audience
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. +Supported values 1 Matched audience 2 Segmented audience 3 Retargeted audience 4 Geofarmed audience 5 Contextual audience 6 Lookalike audience 7 Campaign audience 8 Pre-bid audience 9 Account Based Marketing (ABM) audience 10 Custom Voter audience (CVA) 11 Integrated Care Team (ICT) audience 12 Power Segment audience
audienceStatusId integer	Audience status ID. +Supported values 1 Processing 2 Pending 3 Ready 4 Rejected 5 Deleted 6 Failed 7 Fetching data 8 Data fetched
cpm number	Cost per thousand impressions.
createdAt integer	Creation timestamp (epoch milliseconds).
reach integer	Audience reach.
verticalId integer	Vertical ID. +Supported values 1 Political 2 Healthcare 3 Specialty
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. +Supported values 1 Matched audience 2 Segmented audience 3 Retargeted audience 4 Geofarmed audience 5 Contextual audience 6 Lookalike audience 7 Campaign audience 8 Pre-bid audience 9 Account Based Marketing (ABM) audience 10 Custom Voter audience (CVA) 11 Integrated Care Team (ICT) audience 12 Power Segment audience
audienceSubtypeIds array of integers	Audience subtype IDs to filter by. +Supported values 1 Practitioner 2 D2C 3 HCP 4 NPI nurse 5 Non-NPI nurse 6 Patient
owIds array of integers	Organization Workspace IDs to filter by.
audienceStatusIds array of integers	Audience status IDs to filter by. +Supported values 1 Processing 2 Pending 3 Ready 4 Rejected 5 Deleted 6 Failed 7 Fetching data 8 Data fetched
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

audienceId integer	Audience ID.
audienceName string	Audience name.
audienceTypeId integer	Audience type ID. +Supported values 1 Matched audience 2 Segmented audience 3 Retargeted audience 4 Geofarmed audience 5 Contextual audience 6 Lookalike audience 7 Campaign audience 8 Pre-bid audience 9 Account Based Marketing (ABM) audience 10 Custom Voter audience (CVA) 11 Integrated Care Team (ICT) audience 12 Power Segment audience
audienceSubtypeId integer	Audience subtype ID. +Supported values 1 Practitioner 2 D2C 3 HCP 4 NPI nurse 5 Non-NPI nurse 6 Patient
isIqmIdTargeted boolean	Indicates if IQM ID targeted.
audienceStatusId integer	Audience status ID. +Supported values 1 Processing 2 Pending 3 Ready 4 Rejected 5 Deleted 6 Failed 7 Fetching data 8 Data fetched
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,
        "createdAt": 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. +Supported values 1 Matched audience 2 Segmented audience 3 Retargeted audience 4 Geofarmed audience 5 Contextual audience 6 Lookalike audience 7 Campaign audience 8 Pre-bid audience 9 Account Based Marketing (ABM) audience 10 Custom Voter audience (CVA) 11 Integrated Care Team (ICT) audience 12 Power Segment audience

Response properties

audienceStatusId integer	Audience status ID. +Supported values 1 Processing 2 Pending 3 Ready 4 Rejected 5 Deleted 6 Failed 7 Fetching data 8 Data fetched
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. +Supported values 1 Matched audience 2 Segmented audience 3 Retargeted audience 4 Geofarmed audience 5 Contextual audience 6 Lookalike audience 7 Campaign audience 8 Pre-bid audience 9 Account Based Marketing (ABM) audience 10 Custom Voter audience (CVA) 11 Integrated Care Team (ICT) audience 12 Power Segment audience
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 count by data partner

POST

Get an audience count by data partner ID.

Request schema
audienceTypeId integer	Audience type ID. +Supported values 1 Matched audience 2 Segmented audience 3 Retargeted audience 4 Geofarmed audience 5 Contextual audience 6 Lookalike audience 7 Campaign audience 8 Pre-bid audience 9 Account Based Marketing (ABM) audience 10 Custom Voter audience (CVA) 11 Integrated Care Team (ICT) audience 12 Power Segment audience
owIds string	Organization Workspace IDs.

Response properties

dataPartnerId integer	Data partner ID. +Supported values 7 Healthlink ID 8 Data360 ID 10 IQVIA ID
audienceCount integer	Audience count.

Request sample

{
  "audienceTypeIds": [
    2,
    4
  ],
  "owIds": [
    201427,
    201865
  ]
}

Response 200

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

Matched audience

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. +Supported values 1 Practitioner 2 D2C 3 HCP 4 NPI nurse 5 Non-NPI nurse 6 Patient
audienceStatusId integer	Audience status ID. +Supported values 1 Processing 2 Pending 3 Ready 4 Rejected 5 Deleted 6 Failed 7 Fetching data 8 Data fetched
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. +Supported values 7 Healthlink ID 8 Data360 ID 10 IQVIA 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.

For more information on Matched audiences and how they can serve your Healthcare, Political, or Specialty needs, refer to our Help Center articles.

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. +Supported values 1 Practitioner 2 D2C 3 HCP 4 NPI nurse 5 Non-NPI nurse 6 Patient
columnMappings array	Array of column mapping objects.
columnMappings object properties columnId integer Column ID. fileColumnName string File column name. dataFormatId integer Data format ID. +Supported values 1 Raw 2 Hashed (MD5) 3 Hashed (SHA1) 4 Hashed (SHA256) 5 Hashed (SHA512) 6 Hashed (other)
dataPartnerId integer	Data partner ID. +Supported values 7 Healthlink ID 8 Data360 ID 10 IQVIA ID
columnCombinationId integer	Column combination ID.
consentGiven boolean	Indicates whether consent has been given for patient data usage, required for patient subtype.

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. +Supported values 1 Processing 2 Pending 3 Ready 4 Rejected 5 Deleted 6 Failed 7 Fetching data 8 Data fetched
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);
}

---

Refresh Matched audience

PUT

Rematch/refresh an existing Matched audience's data. Rematching retriggers the audience matching process, updating the audience's reach and matchRate details. The audience must be eligible for rematch based on its status, last rematch time, and other criteria.

Refer to our Help Center articles for more information.

warning

Rematching an audience and changing its reach can impact campaign performance. Exercise caution when rematching an active audience.

Path parameter
audienceId integer	Matched audience ID to be rematched.

Response properties

audienceId integer	Audience ID.
message string	Success message.

Response 200

{
  "success": true,
  "data": {
    "audienceId": 1119083,
    "message": "Test audience rematched successfully via Re-Match"
  }
}

Error 422

{
  "success": false,
  "errorObjects": [
    {
      "error": "No active audience found with the given Id.",
      "field": "audienceId"
    }
  ]
}

---

Geofarmed audience

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. +Supported values 1 Processing 2 Pending 3 Ready 4 Rejected 5 Deleted 6 Failed 7 Fetching data 8 Data fetched
createdAt integer	Creation timestamp (epoch seconds).
reach integer	Audience reach.
cpm number	Cost per thousand impressions.
audienceSubtypeId integer	Audience subtype ID. +Supported values 1 Practitioner 2 D2C 3 HCP 4 NPI nurse 5 Non-NPI nurse 6 Patient
dataPartnerId integer	Data partner ID. +Supported values 7 Healthlink ID 8 Data360 ID 10 IQVIA ID
dataPartnerMetrics array of objects	Data partner metrics.
dataPartnerMetrics object properties id integer Data partner ID. +Supported values 7 Healthlink ID 8 Data360 ID 10 IQVIA ID reach integer Reach for this data partner.
frequency integer	The frequency of visit to the geographical location.
frequencyTypeId integer	Frequency type ID. +Supported values 1 Total 2 Weekly 3 Monthly
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 abbreviation, e.g. US. sid string State abbreviation, e.g. NY. 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 abbreviation, e.g. US. sid string State abbreviation, e.g. NY. 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 abbreviation, e.g. US. sid string State abbreviation, e.g. NY. 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. +Supported values 1 Total 2 Weekly 3 Monthly
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. +Supported values 1 Practitioner 2 D2C 3 HCP 4 NPI nurse 5 Non-NPI nurse 6 Patient
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 abbreviation, e.g. US. sid string State abbreviation, e.g. NY. 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 abbreviation, e.g. US. sid string State abbreviation, e.g. NY. 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);
}

Segmented audience

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. +Supported values 1 Processing 2 Pending 3 Ready 4 Rejected 5 Deleted 6 Failed 7 Fetching data 8 Data fetched
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. +Supported values 1 Political 2 Healthcare 3 Specialty
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.

Using Segment IDs (Search Segmented audiences), you can build an audience with the equation field. Segment IDs in parentheses, separated by a vertical bar (|), are in an 'or' relationship, which combines the sets of Segments; groups of Segments in parentheses, separated by an ampersand (&), are in an 'and' relationship, which builds 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, or you can read more in our Help Center article on Segments Groups and relationships.

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);
}

---

Contextual audience

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. +Supported values 1 Processing 2 Pending 3 Ready 4 Rejected 5 Deleted 6 Failed 7 Fetching data 8 Data fetched
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. +Supported values 7 Healthlink ID 8 Data360 ID 10 IQVIA ID
dataPartnerMetrics array of objects	Data partner metrics.
dataPartnerMetrics object properties id integer Data partner ID. +Supported values 7 Healthlink ID 8 Data360 ID 10 IQVIA 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: the 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.

Contextual audiences support a static or dynamic data collection period of up to 90 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: 90).
audienceSubTypes integer	List of audience subtype IDs to further define the Contextual audience. +Supported values 1 Practitioner 2 D2C 3 HCP 4 NPI nurse 5 Non-NPI nurse 6 Patient

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);
}

CVA Audience

Get Custom Voter audience details

GET

Get Custom Voter 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. +Supported values 1 Processing 2 Pending 3 Ready 4 Rejected 5 Deleted 6 Failed 7 Fetching data 8 Data fetched
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.
equation string	Equation.
stateIds array of integers	State IDs.
segmentList array of objects	Segment list with details.
segmentList object properties segmentId integer Segment ID. taxonomyValue string Taxonomy value. description string Segment description. taxonomyId string Taxonomy ID. isLeaf boolean Indicates if segment is a leaf node. reach integer Segment reach. pathKey string Taxonomy path key. parentSegmentId integer Parent segment ID.
segmentIds array of integers	Segment IDs.

Response 200

{
  "success": true,
  "data": {
    "audienceId": 1234,
    "audienceName": "abc12",
    "audienceStatusId": 1,
    "cpm": 1.5,
    "createdAt": 1764742053642,
    "reach": 0,
    "equation": "(!iqm1123|iqm334)&(iqm1123)",
    "stateIds": [
      123,
      567
    ],
    "segmentList": [
      {
        "segmentId": 123,
        "taxonomyValue": "",
        "description": "",
        "taxonomyId": "iqm1123",
        "isLeaf": true,
        "reach": 80,
        "pathKey": "CA > DEMOGRAPHICS > LANGUAGES > Indian",
        "parentSegmentId": 1
      },
      {
        "segmentId": 124,
        "taxonomyValue": "",
        "description": "",
        "taxonomyId": "iqm334",
        "isLeaf": true,
        "reach": 90,
        "pathKey": "MI > DEMOGRAPHICS > LANGUAGES > Indian",
        "parentSegmentId": 2
      }
    ],
    "segmentIds": [
      123,
      124
    ]
  }
}

---

Get available states for Custom Voter audiences

GET

Get list of available states for Custom Voter audiences. (Note: This endpoint only returns states in the United States.)

Response properties

id integer	State ID.
name string	State name.
abbreviation string	State abbreviation.
parentId integer	Parent region ID.
geojsonUrl string	URL for state geojson file.

Response 200

{
  "success": true,
  "data": {
    "statesList": [
      {
        "id": 123,
        "name": "Alaska",
        "abbreviation": "AK",
        "parentId": 1,
        "geojsonUrl": "https://xyz.com/geojson/AK"
      },
      {
        "id": 456,
        "name": "Alabama",
        "abbreviation": "AL",
        "parentId": 1,
        "geojsonUrl": "https://xyz.com/geojson/AL"
      }
    ],
    "totalRecords": 51,
    "filteredRecords": 2
  }
}

---

Get Custom Voter audience segment details

POST

Browse the Custom Voter audience segment catalogue to find segments to reference in a CVA equation (see Create CVA Details).

The catalogue is a tree. Only leaf segments (isLeaf: true) carry a real, non-zero reach and are valid to reference in an equation. Category/grouping nodes (states, topic groupings, etc.) always report reach: 0 and exist only to organize the tree. A leaf segment's taxonomyId (e.g. IQMCVACA041742) is the exact token to use inside an equation string.

This endpoint fetches the segments based on the search parameters provided:

• If no parameters are provided, it fetches all root segments for the whole country (currently U.S.) along with their child segments.
• If only state IDs are provided, it fetches all root segments for those states along with their child segments.
• If a parent segment ID is provided, it fetches all child segments for that parent segment — this is how you drill down the tree to find leaf segments.
• If search keywords are provided, it fetches all leaf segments matching those keywords in the path key and description.
• If taxonomy IDs are provided, it fetches all leaf segments matching those taxonomy IDs. If the validateTaxonomyIds flag is true, it validates that all taxonomy IDs exist.
• If segment IDs are provided, it fetches those segments.
• If valid supplied search criteria match no segments, it returns an empty list.

Request schema
stateIds array of integers	List of state IDs used to fetch root segments for those states along with their child segments.
parentSegmentId integer	Parent segment ID used to fetch child segments for that parent — use this to drill down the tree.
searchField string	Comma-separated search keywords used to fetch leaf segments matching those keywords in the path key and description.
taxonomyIds array of strings	List of taxonomy IDs used to fetch leaf segments.
validateTaxonomyIds boolean	Flag to validate if all taxonomy IDs provided exist, default: false.
segmentIds array of integers	List of segment IDs used to fetch segments.
pageNo integer	Page number.
noOfEntries integer	Number of entries per page.

Response properties

totalRecords integer	Total number of records matching the request parameters.
filteredRecords integer	Number of filtered records returned.
cvaSegmentData array of objects	Array of CVA segment data objects.
cvaSegmentData object properties segmentId integer Segment ID. taxonomyValue string Human-readable name of the segment. description string Segment description. taxonomyId string Taxonomy ID — for a leaf segment (isLeaf: true), this is the exact token to reference in a CVA equation string. isLeaf boolean Indicates if the segment is a leaf node. Only leaf segments are valid to reference in an equation and carry a real reach value. pathKey string Taxonomy path key, showing the segment's full position in the tree (e.g. California (CA) > Demographics > Gender > F). reach integer Estimated reach of the segment. 0 for non-leaf (category/grouping) nodes; a real, non-zero value only on leaf nodes. parentSegmentId integer Parent segment ID. childSegments array of objects Array of child segment objects (same structure as parent). Only present when drilling into the top-level tree; not returned on every request.

Request examplesSome states selectedAll states selected (PAN-USA)Keyword search with some states selectedKeyword search with all states selected (PAN-USA)Expanding a parent segmentFetching by segment IDsValidating taxonomy IDs

{
  "stateIds": [
    123,
    456
  ],
  "pageNo": 1,
  "noOfEntries": 20
}

{
  "stateIds": [],
  "pageNo": 1,
  "noOfEntries": 20
}

{
  "searchField": "male,female",
  "stateIds": [
    123,
    456
  ],
  "pageNo": 1,
  "noOfEntries": 20
}

{
  "searchField": "male,female",
  "stateIds": [],
  "pageNo": 1,
  "noOfEntries": 20
}

{
  "parentSegmentId": 123,
  "pageNo": 1,
  "noOfEntries": 20
}

{
  "segmentIds": [
    123,
    456
  ],
  "pageNo": 1,
  "noOfEntries": 20
}

{
  "taxonomyIds": [
    "iqm123",
    "iqm234"
  ],
  "validateTaxonomyIds": true,
  "pageNo": 1,
  "noOfEntries": 20
}

Response 200 examplesSegment details for some selected statesSegment details for all states selected (PAN-USA)Segment details for a keyword searchInvalid taxonomy IDs provided

{
  "success": true,
  "data": {
    "totalRecords": 100,
    "cvaSegmentData": [
      {
        "segmentId": 1,
        "taxonomyValue": "California",
        "description": "California state",
        "taxonomyId": "iqmcva1",
        "isLeaf": false,
        "pathKey": "California (CA)",
        "reach": 0,
        "parentSegmentId": 0,
        "childSegments": [
          {
            "segmentId": 157,
            "taxonomyValue": "Age",
            "description": "Age segment",
            "isLeaf": false,
            "taxonomyId": "iqmcva157",
            "pathKey": "California (CA) > Age",
            "parentSegmentId": 1,
            "reach": 0
          },
          {
            "segmentId": 158,
            "taxonomyValue": "Demographics",
            "description": "Demographics segment",
            "isLeaf": false,
            "taxonomyId": "iqmcva158",
            "pathKey": "California (CA) > Demographics",
            "parentSegmentId": 1,
            "reach": 0
          },
          {
            "segmentId": 159,
            "taxonomyValue": "Gender",
            "description": "Gender segment",
            "isLeaf": false,
            "taxonomyId": "iqmcva159",
            "pathKey": "California (CA) > Gender",
            "parentSegmentId": 1,
            "reach": 0
          }
        ]
      },
      {
        "segmentId": 2,
        "taxonomyValue": "New York",
        "description": "New York state",
        "taxonomyId": "iqmcva2",
        "isLeaf": false,
        "pathKey": "New York (NY)",
        "reach": 0,
        "parentSegmentId": 0,
        "childSegments": [
          {
            "segmentId": 160,
            "taxonomyValue": "Age",
            "description": "Age segment",
            "isLeaf": false,
            "taxonomyId": "iqmcva160",
            "pathKey": "New York (NY) > Age",
            "parentSegmentId": 2,
            "reach": 0
          },
          {
            "segmentId": 161,
            "taxonomyValue": "Demographics",
            "description": "Demographics segment",
            "isLeaf": false,
            "taxonomyId": "iqmcva161",
            "pathKey": "New York (NY) > Demographics",
            "parentSegmentId": 2,
            "reach": 0
          },
          {
            "segmentId": 162,
            "taxonomyValue": "Gender",
            "description": "Gender segment",
            "isLeaf": false,
            "taxonomyId": "iqmcva162",
            "pathKey": "New York (NY) > Gender",
            "parentSegmentId": 2,
            "reach": 0
          }
        ]
      }
    ],
    "filteredRecords": 2
  }
}

{
  "success": true,
  "data": {
    "totalRecords": 100,
    "cvaSegmentData": [
      {
        "segmentId": 1,
        "taxonomyValue": "Age",
        "description": "Age segment",
        "taxonomyId": "iqmcva1",
        "isLeaf": false,
        "pathKey": "Age",
        "reach": 0,
        "parentSegmentId": 0,
        "childSegments": [
          {
            "segmentId": 157,
            "taxonomyValue": "Age greater than 20",
            "description": "Age segment",
            "isLeaf": true,
            "taxonomyId": "IQMCVAUS041742",
            "pathKey": "Age > Greater than 20",
            "parentSegmentId": 1,
            "reach": 145003462
          },
          {
            "segmentId": 158,
            "taxonomyValue": "Age greater than 40",
            "description": "Age segment",
            "isLeaf": true,
            "taxonomyId": "IQMCVAUS041743",
            "pathKey": "Age > Greater than 40",
            "parentSegmentId": 1,
            "reach": 132558211
          },
          {
            "segmentId": 159,
            "taxonomyValue": "Age greater than 60",
            "description": "Age segment",
            "isLeaf": true,
            "taxonomyId": "IQMCVAUS041744",
            "pathKey": "Age > Greater than 60",
            "parentSegmentId": 1,
            "reach": 98421007
          }
        ]
      },
      {
        "segmentId": 2,
        "taxonomyValue": "Demographics",
        "description": "Demographics segment",
        "taxonomyId": "iqmcva2",
        "isLeaf": false,
        "pathKey": "Demographics",
        "parentSegmentId": 0,
        "reach": 0,
        "childSegments": [
          {
            "segmentId": 160,
            "taxonomyValue": "Demographics 1",
            "description": "Demographics segment",
            "isLeaf": true,
            "taxonomyId": "IQMCVAUS041745",
            "pathKey": "Demographics > D1",
            "parentSegmentId": 2,
            "reach": 4002462
          },
          {
            "segmentId": 161,
            "taxonomyValue": "Demographics 2",
            "description": "Demographics segment",
            "isLeaf": true,
            "taxonomyId": "IQMCVAUS041746",
            "pathKey": "Demographics > D2",
            "parentSegmentId": 2,
            "reach": 3811290
          },
          {
            "segmentId": 162,
            "taxonomyValue": "Demographics 3",
            "description": "Demographics segment",
            "isLeaf": false,
            "taxonomyId": "iqmcva162",
            "pathKey": "Demographics > D3",
            "parentSegmentId": 2,
            "reach": 0
          }
        ]
      }
    ],
    "filteredRecords": 2
  }
}

{
  "success": true,
  "data": {
    "totalRecords": 100,
    "cvaSegmentData": [
      {
        "segmentId": 157,
        "taxonomyValue": "Age greater than 20",
        "description": "Age segment",
        "isLeaf": true,
        "taxonomyId": "IQMCVACA041742",
        "pathKey": "California (CA) > Age > Greater than 20",
        "parentSegmentId": 1,
        "reach": 11789748
      },
      {
        "segmentId": 158,
        "taxonomyValue": "Age greater than 40",
        "description": "Age segment",
        "isLeaf": true,
        "taxonomyId": "IQMCVACA041743",
        "pathKey": "California (CA) > Age > Greater than 40",
        "parentSegmentId": 1,
        "reach": 10334521
      },
      {
        "segmentId": 159,
        "taxonomyValue": "Age greater than 60",
        "description": "Age segment",
        "isLeaf": true,
        "taxonomyId": "IQMCVACA041744",
        "pathKey": "California (CA) > Age > Greater than 60",
        "parentSegmentId": 1,
        "reach": 8221903
      }
    ],
    "filteredRecords": 3
  }
}

{
  "success": false,
  "data": {
    "invalidTaxonomyIds": [
      "imq-123"
    ]
  }
}

---

Create Custom Voter audience

POST

Create a Custom Voter audience by providing audience details in the request body. The response includes the created audience ID which can be used to retrieve audience details and apply the audience to campaigns.

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, or you can read more in our Help Center article on Segments Groups and Relationships.

Request body properties
audienceName string	Audience name.
equation string	Equation string representing the segment ID groups in AND/OR relationship.
reach integer	Audience reach.
audienceSize number	Audience size as a percentage (0-100).
stateIds array of integers	State IDs (Audience will include all states by default if no IDs are included.).

Response properties

id integer	Audience ID.
message string	Response message.

Request sample

{
  "audienceName": "sampleAudienceName1",
  "equation": "(iqm1234&iqm3456)|(iqm21345|!iqm45675)",
  "reach": 1234566,
  "audienceSize": 24.57,
  "stateIds": [
    123,
    456
  ]
}

Response 200

{
  "success": true,
  "data": {
    "id": 1143140,
    "message": "Custom Voter audience created successfully"
  }
}

---

Get CVA reach

POST

Get reach data for a Custom Voter audience.

See the Create Custom Voter audience endpoint for details on the equation parameter.

Request schema
equation string	Equation string representing the segment ID groups in AND/OR relationship.
state_ids array of integers	State IDs.

Response properties

segment_num_voters integer	Number of voters in the segment matching the equation criteria.
total_num_voters integer	Total number of voters across all selected states.
map_metrics object	Party registration breakdown by state ID.
map_metrics object properties {stateId} object Voter counts by party (Republican, Democrat, Other) for the given state.

Request sample

{
  "equation":"((IQMCVACA069112))",
  "state_ids":["30200005"]
}

Response 200

{
    "success": true,
    "data": {
        "segment_num_voters": 2887320,
        "total_num_voters": 23165810,
        "map_metrics": {
            "30200005": {
                "Republican": 664123,
                "Democrat": 1202940,
                "Other": 1020257
            }
        }
    }
}

---

Get CVA Insights

POST

Get Insights data for a Custom Voter audience, including demographic breakdowns for party registration, gender, urbanicity, age, and ethnicity.

See the Create Custom Voter audience endpoint for details on the equation parameter.

Request schema
equation string	Equation string representing the segment ID groups in AND/OR relationship.
state_ids array of integers	State IDs.

Response properties

segment_num_voters integer	Total number of voters in the segment.
insights object	Demographic breakdown of voters in the segment.
insights object properties party_registration object Voter counts by party registration (e.g., Democratic, Republican, Others). gender object Voter counts by gender (e.g., Male, Female, Unknown). urbanicity object Voter counts by urbanicity (e.g., Urban, Rural, Sub-Urban, Unknown). age object Voter counts by age range (e.g., 18-20, 21-24, 25-34, 35-44, 45-54, 55-64, 65+). ethnicity object Voter counts by ethnicity.

Request sample

{
  "equation":"((IQMCVACA069112))",
  "state_ids":["30200005"]
}

Response 200

{
    "success": true,
    "data": {
        "segment_num_voters": 2887320,
        "insights": {
            "party_registration": {
                "Others": 18529,
                "Democratic": 1202940,
                "Republican": 664123
            },
            "gender": {
                "Male": 2799766,
                "Unknown": 86698,
                "Female": 856
            },
            "urbanicity": {
                "Urban": 2104851,
                "Rural": 235643,
                "Unknown": 647,
                "Sub-Urban": 546179
            },
            "age": {
                "18-20": 98295,
                "55-64": 395914,
                "35-44": 560105,
                "25-34": 641809,
                "Unknown": 1287,
                "45-54": 377989,
                "21-24": 180553,
                "65+": 631368
            },
            "ethnicity": {
                "Scots": 92125,
                "Filipino": 12130,
                "Tonga": 70,
                "Ukrainian": 1434,
                "Icelandic": 56,
                "Maldivian": 12,
                "Armenian": 16818,
                "Greek": 6766,
                "Norwegian": 9410,
                "Slovenian": 485,
                "Irish": 114132,
                "Uzbek": 51,
                "Dutch (Netherlands)": 24345,
                "Lithuanian": 1016,
                "Austrian": 4745,
                "Pakistani": 4233,
                "Turkish": 2162,
                "Basque": 3,
                "Arab": 58847,
                "Polish": 14424,
                "Bosnian Muslim": 79,
                "Italian": 102771,
                "Indian/Hindu": 52524,
                "Kirghiz": 2,
                "unknown": 314065,
                "Slovakian": 1256,
                "Danish": 2811,
                "Nepalese": 4,
                "Serbian": 2312,
                "Persian": 10578,
                "Laotian": 3235,
                "Khmer": 1896,
                "Hawaiian": 1454,
                "Belgian": 885,
                "Kazak": 12,
                "Tibetan": 158,
                "Native American": 332,
                "Afghan": 747,
                "Bhutanese": 153,
                "Georgian": 78,
                "Chinese": 113393,
                "Finnish": 1698,
                "Bangladeshi": 131,
                "Chechnian": 108,
                "Macedonian": 21,
                "Manx": 13,
                "Tajik": 7,
                "African or Af-Am Self Reported": 709,
                "Vietnamese": 49542,
                "Kurdish": 367,
                "Romanian": 1849,
                "Hispanic": 906044,
                "Russian (omitting former Soviet States)": 13926,
                "Western Samoa": 43,
                "Myanmar (Burmese)": 1954,
                "Nauruan": 1,
                "Thai": 2287,
                "Estonian": 495,
                "English/Welsh": 582938,
                "Croatian": 860,
                "Moldavian": 8,
                "French": 38330,
                "Swedish": 22868,
                "Czech": 4310,
                "German": 112880,
                "Japanese": 17738,
                "Swiss": 365,
                "Latvian": 386,
                "Multi-Ethnic": 18,
                "Portuguese": 4511,
                "Luxembourgian": 66,
                "Papua New Guinea": 11,
                "Likely Af-Am (Modeled)": 109723,
                "Bulgarian": 841,
                "Albanian": 302,
                "Malay": 71,
                "Australian": 14,
                "Korean": 29395,
                "Byelorussian": 1351,
                "Indonesian": 446,
                "Mongolian": 403,
                "Sri Lankan": 166,
                "Azerb": 57,
                "Unknown Asian": 2682,
                "Hungarian": 5337,
                "Turkmenistan": 39
            }
        }
    }
}

Power Segment audience

Power Segment audience details

GET

Get Power Segment audience details by ID, including the resolved list of active segments (Sphere/Orbit) selected by its equation, ordered by segment ID. Segments that are no longer active are left out.

Path parameter
audienceId integer	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	Estimated reach of the audience.
cpm number	Cost per mille.
segments array of objects	List of segments (Sphere/Orbit) selected by this audience.
segments object properties personalityId string Personality ID the segment belongs to. personalityName string Name of the personality. jobTitle string Job title of the personality. category string Category the personality belongs to. segmentType string Segment type: Sphere or Orbit. reach integer Estimated reach of the segment. cpm number Cost per mille for the segment. dataUpdatedAt integer Timestamp when the segment data was last updated (epoch milliseconds). segmentStatus string Status of the segment. taxonomyId string Taxonomy ID of the segment. insights object properties status string Status of the insight. generationTime integer Timestamp when the insight was generated. sizeInBytes integer Size of the insight, in bytes.

JSON

Response 200

{
  "success": true,
  "data": {
    "audienceId": 1140623,
    "audienceName": "Test Power Segment audience",
    "audienceStatusId": 3,
    "createdAt": 1718796428,
    "reach": 184500,
    "cpm": 12.5,
    "segments": [
      {
        "personalityId": "761d7017-857c-3074-adb2-4d74ad7702da",
        "personalityName": "Scott Bessent",
        "jobTitle": "Chief Investment Officer",
        "category": "Cabinet Members",
        "segmentType": "Orbit",
        "reach": 184500,
        "cpm": 12.5,
        "dataUpdatedAt": 1718796428
      }
    ]
  }
}

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;
          segments: {
            personalityId: string;
            personalityName: string;
            jobTitle: string;
            category: string;
            segmentType: string;
            reach: number;
            cpm: number;
            dataUpdatedAt: number;
            segmentStatus: string;
            taxonomyId: string;
            insights?: {
              status: string;
              generationTime: number;
              sizeInBytes: number;
            };
          }[];
        };
      };
    };
  };
}

function getPowerSegmentAudience(): Promise<Responses> {
  const options = {
    method: 'GET',
    url: 'https://api.iqm.com/api/v3/audience/power-segment/{audienceId}',
    params: {
      includeInsight: false
    }
  };

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

---

Create Power Segment audience

POST

Create a Power Segment audience. Only available to advertisers under the Political vertical.

Request schema
audienceName string required	Audience name.
equation string required	Equation representing the combination of Power Segment taxonomy IDs, using taxonomy IDs and the OR operator (|), wrapped in a double set of parentheses. Every taxonomy ID must belong to an active segment that is either a standard segment or private to the logged-in organization.

Response properties

audienceId integer	Audience ID.
message string	Success message.

JSON

Request sample

{
  "audienceName": "Test Power Segment audience",
  "equation": "((IQMADV12345|IQMADV67890))"
}

Response 200

{
  "success": true,
  "data": {
    "audienceId": 1140623,
    "message": "Test Power Segment 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 createPowerSegmentAudience(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/audience/power-segment',
    requestBody: {
      content: {
        "application/json": {
          audienceName: `string`,
          equation: `string`
        }
      }
    }
  };

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

---

Update Power Segment audience

PUT

Update the name and equation of an existing Power Segment audience. Only available to advertisers under the Political vertical.

Path parameter
audienceId integer	Audience ID.

Request schema
audienceName string required	Audience name.
equation string required	Equation representing the combination of Power Segment taxonomy IDs, using taxonomy IDs and the OR operator (|), wrapped in a double set of parentheses. Every taxonomy ID must belong to an active segment that is either a standard segment or private to the logged-in organization.

Response properties

audienceId integer	Audience ID.
message string	Success message.

JSON

Request sample

{
  "audienceName": "Updated Power Segment audience",
  "equation": "((IQMADV12345|IQMADV67890))"
}

Response 200

{
  "success": true,
  "data": {
    "audienceId": 1140623,
    "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 updatePowerSegmentAudience(): Promise<Responses> {
  const options = {
    method: 'PUT',
    url: 'https://api.iqm.com/api/v3/audience/power-segment/{audienceId}',
    requestBody: {
      content: {
        "application/json": {
          audienceName: `string`,
          equation: `string`
        }
      }
    }
  };

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

---

List/search Power Segments

POST

Search and filter Power Segments.

The individual tab shows active standard segments plus the caller's org's private active segments; the requested tab shows only the caller's org's private segments that are active, requested, or failed. Favorite status is resolved for the logged-in user.

Request schema
pageNo integer	Page number of retrieved data.
noOfEntries integer	Number of entries returned per page.
sortBy string	Sorts by ascending (+) or descending (-), e.g. +personalityName,-category.
searchField string	Search personalities by name.
tab string required	Tab being viewed: individual or requested.
favorite boolean	When true, restricts results to personalities favorited by the logged-in user.
categories array of strings	Power Segment category type names to filter by, e.g. CABINET_MEMBERS.
taxonomyIds array of strings	When provided, restricts results to personalities owning any of these Sphere or Orbit taxonomy IDs. Max 100.

Response properties

totalRecords integer	Total number of personalities for the selected tab/org scope.
filteredRecords integer	Number of personalities matching the search/filter criteria.
segmentsList array of objects	Personalities matching the search/filter criteria.
segmentsList object properties personalityId string Personality ID, used to favorite/unfavorite this personality. Shared by the personality's Sphere and Orbit segments. personalityName string Name of the personality. jobTitle string Job title of the personality. category string Power Segment category type display name. description string Description of the personality. favorite boolean Whether the logged-in user has favorited this personality. sphere object The personality's Sphere segment, present only if one exists. orbit object The personality's Orbit segment, present only if one exists. Same shape as sphere. sphere/orbit object properties taxonomyId string Taxonomy ID of the segment. cpm number Cost per mille. totalReach integer Estimated reach of the segment. dataUpdatedAt integer Timestamp when the segment data was last updated (epoch milliseconds). status string Status of the segment. dataAvailable boolean Whether segment data is currently available. insights object Insight generation status for the segment. insights object properties status string Status of the insight. generationTime integer Timestamp when the insight was generated. sizeInBytes integer Size of the insight, in bytes.

JSON

Request sample

{
  "pageNo": 1,
  "noOfEntries": 20,
  "sortBy": "+personalityName,-category",
  "searchField": "Bessent",
  "tab": "individual",
  "favorite": false,
  "categories": ["CABINET_MEMBERS"],
  "taxonomyIds": ["IQMADV-1004"]
}

Response 200

{
  "success": true,
  "data": {
    "totalRecords": 340,
    "filteredRecords": 12,
    "segmentsList": [
      {
        "personalityId": "761d7017-857c-3074-adb2-4d74ad7702da",
        "personalityName": "Scott Bessent",
        "jobTitle": "Secretary of the Treasury",
        "category": "Cabinet Members",
        "description": "Scott Bessent",
        "favorite": true,
        "sphere": {
          "taxonomyId": "IQMADV-1004",
          "cpm": 12.5,
          "totalReach": 184500,
          "dataUpdatedAt": 1780272000000,
          "status": "active",
          "dataAvailable": true,
          "insights": {
            "status": "Ready",
            "generationTime": 2592002592002,
            "sizeInBytes": 499851
          }
        }
      }
    ]
  }
}

Response 422 (missing/invalid tab)

{
  "success": false,
  "errorObjects": [
    { "error": "tab must be either \"individual\" or \"requested\"." }
  ]
}

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;
          segmentsList: {
            personalityId: string;
            personalityName: string;
            jobTitle: string;
            category: string;
            description: string;
            favorite: boolean;
            sphere?: {
              taxonomyId: string;
              cpm: number;
              totalReach: number;
              dataUpdatedAt: number;
              status: string;
              dataAvailable: boolean;
              insights: {
                status: string;
                generationTime: number;
                sizeInBytes: number;
              };
            };
            orbit?: {
              taxonomyId: string;
              cpm: number;
              totalReach: number;
              dataUpdatedAt: number;
              status: string;
              dataAvailable: boolean;
              insights: {
                status: string;
                generationTime: number;
                sizeInBytes: number;
              };
            };
          }[];
        };
      };
    };
  };
}

function getPowerSegmentSearchList(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/audience/power-segment/segments/search/list',
    requestBody: {
      content: {
        "application/json": {
          pageNo: `number`,
          noOfEntries: `number`,
          sortBy: `string`,
          searchField: `string`,
          tab: `string`,
          favorite: `boolean`,
          categories: `string[]`,
          taxonomyIds: `string[]`
        }
      }
    }
  };

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

---

Request a custom Power Segment

POST

Submits a custom Power Segment request for a personality, private to the logged-in organization. One segment is created per requested segmentType with status requested.

If only orbit is requested, a deleted Sphere segment is also created for the personality; if only sphere is requested, no Orbit segment is created. Political vertical advertiser users only.

Request schema
personalityName string required	Name of the personality the segment is requested for.
segmentType array of strings required	Segment types requested for the personality (case-insensitive): sphere, orbit, or both.
additionalDetails string required	Free-text details to help fulfil the request.

Response properties

message string

Success message.

JSON

Request sample

{
  "personalityName": "Scott Bessent",
  "segmentType": ["sphere", "orbit"],
  "additionalDetails": "Include recent congressional activity"
}

Response 200

{
  "success": true,
  "data": {
    "message": "Scott Bessent Request submitted successfully. We'll notify you by email once available. Expected turnaround: 2 business days."
  }
}

Response 400 (missing personalityName)

{
  "success": false,
  "errorObjects": [
    {
      "error": "personalityName is required and can not be blank.",
      "field": "personalityName"
    }
  ]
}

Response 422 (invalid segmentType)

{
  "success": false,
  "errorObjects": [
    { "error": "Invalid segmentType provided. Allowed values: \"sphere\", \"orbit\"." }
  ]
}

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 createPowerSegmentRequest(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/audience/power-segment/segments/request',
    requestBody: {
      content: {
        "application/json": {
          personalityName: `string`,
          segmentType: `string[]`,
          additionalDetails: `string`
        }
      }
    }
  };

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

---

Add Power Segment personality to favorites

POST

Marks a Power Segment personality as a favorite for the logged-in user. Idempotent: favoriting an already-favorited personality still returns success.

Path parameter
personalityId string	Personality ID.

Response properties

message string

Success message.

JSON

Response 200

{
  "success": true,
  "data": {
    "message": "Personality added to favorites"
  }
}

Response 422 (personality not found)

{
  "success": false,
  "errorObjects": [
    { "error": "No power segment personality found for the provided personality ID." }
  ]
}

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 addPersonalityToFavorites(): Promise<Responses> {
  const options = {
    method: 'POST',
    url: 'https://api.iqm.com/api/v3/audience/power-segment/segments/{personalityId}/favorite',
  };

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

---

Remove Power Segment personality from favorites

DELETE

Unmarks a Power Segment personality as a favorite for the logged-in user.

Idempotent: removing a personality that isn't currently favorited still returns success, regardless of whether the personality's segment still exists or is active.

Path parameter
personalityId string	Personality ID.

Response properties

message string

Success message.

JSON

Response 200

{
  "success": true,
  "data": {
    "message": "Personality removed from favorites"
  }
}

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 removePersonalityFromFavorites(): Promise<Responses> {
  const options = {
    method: 'DELETE',
    url: 'https://api.iqm.com/api/v3/audience/power-segment/segments/{personalityId}/favorite',
  };

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

---

Power Segment category type list

GET

Get a static list of Power Segment category types.

Use name as a value for the categories filter in the List/search Power Segments endpoint.

Response properties

id integer	Category type ID.
name string	Category type name.
displayName string	Category type display name.
order integer	Order.

JSON

Response 200

{
  "success": true,
  "data": [
    { "id": 1, "name": "CABINET_MEMBERS", "order": 10, "displayName": "Cabinet Members" },
    { "id": 2, "name": "GOVERNOR", "order": 20, "displayName": "Governor" },
    { "id": 3, "name": "HOUSE_OF_REPRESENTATIVE", "order": 30, "displayName": "House of Representative" },
    { "id": 4, "name": "SENATOR", "order": 40, "displayName": "Senator" },
    { "id": 5, "name": "MAYOR", "order": 50, "displayName": "Mayor" },
    { "id": 6, "name": "PERSONALITIES", "order": 60, "displayName": "Personalities" }
  ]
}

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;
          displayName: string;
          order: number;
        }[];
      };
    };
  };
}

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

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

More audience details

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.
  +Supported values

  1	Matched audience
  2	Segmented audience
  3	Retargeted audience
  4	Geofarmed audience
  5	Contextual audience
  6	Lookalike audience
  7	Campaign audience
  8	Pre-bid audience
  9	Account Based Marketing (ABM) audience
  10	Custom Voter audience (CVA)
  11	Integrated Care Team (ICT) audience
  12	Power Segment audience

• 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. +Supported values 1 Matched audience 2 Segmented audience 3 Retargeted audience 4 Geofarmed audience 5 Contextual audience 6 Lookalike audience 7 Campaign audience 8 Pre-bid audience 9 Account Based Marketing (ABM) audience 10 Custom Voter audience (CVA) 11 Integrated Care Team (ICT) audience 12 Power Segment audience
audienceSubtypeIds integer	Audience subtype IDs. +Supported values 1 Practitioner 2 D2C 3 HCP 4 NPI nurse 5 Non-NPI nurse 6 Patient
verticalId integer	Vertical ID. +Supported values 1 Political 2 Healthcare 3 Specialty
active boolean	Filter for active data partners.

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);
}

---

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. +Supported values 1 Matched audience 2 Segmented audience 3 Retargeted audience 4 Geofarmed audience 5 Contextual audience 6 Lookalike audience 7 Campaign audience 8 Pre-bid audience 9 Account Based Marketing (ABM) audience 10 Custom Voter audience (CVA) 11 Integrated Care Team (ICT) audience 12 Power Segment audience
verticalId integer	Vertical ID. +Supported values 1 Political 2 Healthcare 3 Specialty

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. If audienceTypeIds isn't provided, audience statuses for all audience types are fetched.

Query parameters
audienceTypeIds array of integers	Audience type IDs to fetch applicable audience statuses for. +Supported values 1 Matched audience 2 Segmented audience 3 Retargeted audience 4 Geofarmed audience 5 Contextual audience 6 Lookalike audience 7 Campaign audience 8 Pre-bid audience 9 Account Based Marketing (ABM) audience 10 Custom Voter audience (CVA) 11 Integrated Care Team (ICT) audience 12 Power Segment audience
verticalIds array of integers	Vertical IDs to filter audience statuses by (default: all verticals). +Supported values 1 Political 2 Healthcare 3 Specialty
deletedStatusRequired boolean	Whether to include the Deleted status in the response (default: false).

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-types',
  };

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

---

---