Skip to main content

Audience API

The Audience API allows you to create Segmented Audiences for political Campaigns.

The following table describes some of the Audience types:

TypeDescription
Matched AudienceUpload a CSV or XLSX file with Audience details which is then matched with IQM's user database to create a custom Segmented Audience.
Geo-Farmed AudienceDefine an Audience by a custom geographical area.
Segmented AudienceGroup users by common characteristics to reach specific target Audiences.
Contextual AudienceIQM adds users to an Audience when they visit sites featuring specified keywords or URLs.

More Resources​

Authentication​

Use the following header parameters for all requests:

Headers
Authentication
string required		Authentication bearer token
See Authentication Guide
X-IAA-OW-ID
integer required		Organization Workspace ID Header

Audience Details​

Audience Details List​

GET

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

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

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

Request Schema
audienceIds
array of integers		Audience IDs to filter by
audienceTypeIds
array of integers		Audience Type IDs to filter by
audienceSubtypeIds
array of integers		Audience Subtype IDs to filter by
owIds
array of integers		Organization Workspace IDs to filter by
audienceStatusIds
array of integers		Audience Status IDs to filter by
includeGenericAudience
boolean		Include generic audiences
audienceTypeIdsWithAllSubtypes
array of integers		Audience Type IDs to include all subtypes
pageNo
integer		Page number of retrieved data
noOfEntries
integer		Number of entries returned per page
sortBy
string		Sorts results by specified field
searchFields
array		Filter results by search fields
Response Properties
audienceId
integer		Audience ID
audienceName
string		Audience name
audienceTypeId
integer		Audience Type ID
audienceStatusId
integer		Audience Status ID
cpm
number		Cost per thousand impressions
createdAt
integer		Creation timestamp (epoch milliseconds)
reach
integer		Audience reach
verticalId
integer		Vertical ID
organizationName
string		Organization name
runningCampaignCount
integer		Number of running campaigns
pendingCampaignCount
integer		Number of pending campaigns
pausedCampaignCount
integer		Number of paused campaigns
expiredCampaignCount
integer		Number of expired campaigns
startDate
integer		Start date (epoch milliseconds)
endDate
integer		End date (epoch milliseconds)
timezone
integer		Timezone ID
regeneratedCount
integer		Number of times regenerated
matchRate
number		Match rate percentage
fileTotalCount
integer		Total number of files
s3FileName
string		S3 file name
approvalAccess
boolean		Approval access permission
editAccess
boolean		Edit access permission
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
            }
        ]
    }
}

Matched Audience Details​

GET

Get Matched Audience details by ID.

Path Parameter
audienceId
string		Matched Audience ID
Query Parameters
campaignTargetingRequired
boolean		(Optional) Flag to indicate if campaign targeting details are returned, default: false
userDetailsRequired
boolean		(Optional) Flag to indicate if user details are returned, default: false
Response Properties
audienceId
integer		Audience ID
audienceName
string		Audience name
audienceSubtypeId
integer		Audience subtype ID
audienceStatusId
integer		Audience status ID
cpm
number		Cost per thousand impressions
owId
integer		Organization Workspace ID
createdByUowId
integer		Created by User Organization Workspace ID
createdAt
integer		Unix epoch creation date (milliseconds)
reach
integer		Audience reach
s3FileName
string		Audience file name
s3Url
string		S3 URL of the audience file
fileRowCount
integer		Number of rows in the file
matchRate
number		The percentage of matched records compared to a reference set
dataPartnerId
integer		Data partner ID
modifiedAt
string		Modified date (ISO 8601 format)
approvalAccess
boolean		Indicates if user has access to approve
editAccess
boolean		Indicates if user has edit access for the requested resource
whitelistedCampaignIds
array		Array of whitelisted Campaign IDs
blacklistedCampaignIds
array		Array of blacklisted Campaign IDs
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
  }
}

Geofarmed Audience Details​

GET

Get Geofarmed Audience Details by ID.

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

Contextual Audience Details​

GET

Get Contextual Audience details by ID.

Path Parameter
audienceId
string		Audience ID
Response Properties
audienceId
integer		Audience ID
audienceName
string		Audience name
audienceStatusId
integer		Audience status ID
cpm
number		Cost per thousand impressions
reach
integer		Audience reach
createdAt
integer		Unix epoch creation date (milliseconds)
keywords
array of strings		Keywords
urls
array of strings		URLs
dataCollectionMethodId
integer		Data collection method ID
dataCollectionDays
integer		Data collection days
frequency
integer		Frequency
dataPartnerId
integer		Data partner ID
dataPartnerMetrics
array of objects		Data partner metrics
dataPartnerMetrics object properties
id
integer		Data partner ID
reach
integer		Reach for this data partner
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
      }
    ]
  }
}

Segmented Audience Details​

Segmented Audience Details​

GET

Get Segmented Audience details by ID.

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

Search Segmented Audiences​

POST
POST

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

Request Schema
pageNo
integer		Page number for the required data, default: 1
noOfEntries
integer		Maximum number of returned results per page, default: 100
sortBy
string		Sorts results by specified field. For ascending use plus(+) sign and for descending use minus (-) sign
searchKeywordSet
array of strings		Search keywords to be searched on the 'pathKey' and 'description' of the segments with encoded special characters (required if segmentIds not given)
segmentIds
array of integers		Segment IDs to filter returned data by (required if searchKeywordSet not given)
verticalIds
array of integers		Vertical IDs to filter returned data by
partnerIds
array of integers		Partner IDs to filter returned data by
providerIds
array of integers		Provider IDs to filter returned data by
priceRangeIds
array of integers		Price Range IDs to filter returned data by
reachRangeIds
array of integers		Reach Range IDs to filter returned data by
showOnlyReadySegments
boolean		Flag to filter segments that are ready, default: false
showOnlyNonZeroSegments
boolean		Flag to filter segments that have non-zero reach, default: false
Response Properties
segmentId
integer		Segment ID
taxonomyValue
string		Taxonomy value
description
string		Description
pathKey
string		A hierarchichal key representing the taxonomy's path or structure
cpm
integer		Cost per mille
referenceId
string		Reference ID
lastUpdateDate
string		Date when last updated
totalReach
integer		Total reach
providerId
integer		Provider ID
partnerId
integer		Partner ID
reachMetadata
object		Reach metadata object details
reachMetadata object properties
iosDevicesReach
integer		IOS devices reach
androidDevicesReach
integer		Android devices reach
cookiesReach
integer		Cookies reach
logoUrl
string		Logo URL
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"            
      }        
    ]    
  }
}

Audience Management​

Create Matched Audience​

POST

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

Request Schema
audienceRequest
form data required		Audience metadata details
file
multipart/form-data required		File to be uploaded
audienceRequest Properties
audienceName
string		Audience Name
fileRowCount
integer		Number of rows in the file
fileColumnCount
integer		Number of columns in the file
audienceSubtypeId
integer		Audience Subtype ID
columnMappings
array		Array of column mapping objects
columnMappings object properties
columnId
integer		Column ID
fileColumnName
string		File column name
dataFormatId
integer		Data Format ID
dataPartnerId
integer		Data Partner ID
columnCombinationId
integer		Column Combination ID

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

audienceRequest sample object for Healthcare Matched Audience
{
  "audienceName": "Revamped Healthcare Matched Audience 02",
  "dataPartnerId": 7,
  "audienceSubtypeId": 3,
  "columnMappings": [
      {
          "columnId": 18,
          "fileColumnName": "NPI_ID"
      }
  ],
  "fileRowCount": 19,
  "fileColumnCount": 1,
  "columnCombinationId": 14,
  "consentGiven": true
}
POST /api/v3/audience/matched HTTP/1.1
Host: api.iqm.com
Authorization: Bearer 0ed52da8-24ab-44b1-bc88-7ea03a090d24
X-IAA-OW-ID: 1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

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

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

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

Update Matched Audience​

PATCH

Update a Matched Audience.

Path Parameter
audienceId
integer		Matched Audience ID
Request Schema
dataCost
number		Data cost
audienceStatusId
integer		Audience Status ID
rejectionReason
string		Reason for rejection if updating status to Rejected
Response Properties
id
integer		Audience ID
message
string		Success message
Request Sample
{
  "dataCost": 10,
  "audienceStatusId": 4,
  "rejectionReason": "Insufficient data quality."
}
Response 200
{
  "statusCode": 200,
  "responseObject": {
    "id": 1,
    "message": "Your changes have been saved successfully"
  }
}

Create Segmented Audience​

POST

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

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

Request Schema
equation
string required		Equation string representing the segment ID groups in AND/OR relationship
audienceName
string required		Name of the segmented audience to be created (maximum 255 characters)
Response Properties
id
integer		Audience ID
message
string		Success message
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"
  }
}

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
Request Sample
{
  "equation": "((5613837|5638265)&(5613844))",
  "name": "Segment audience - 1"
}
Response 200
{
  "success": true,
  "data": {
    "audienceId": 1140623,
    "message": "<Audience Name> audience updated successfully"
  }
}

Create Geofarmed Audience​

POST

Create a Geofarmed Audience.

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

Response Properties
id
integer		Audience ID
message
string		Success message
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"
  }
}

Create Contextual Audience​

POST

Create a Contextual Audience.

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

info

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

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

Request Schema
audienceName
string		Audience name
keywords
array of strings		Keywords to generate contextual Audience
startDate
integer		Unix epoch start date, in milliseconds (required if data collection method is static)
endDate
integer		Unix epoch start date, in milliseconds (required if data collection method is static)
frequency
integer		The number of times a user visits the publisher(s) relevant to one or more keywords or URLs added to the contextual Audience. Integer between 1-10
urls
array of strings		The publisher sites visited by a user
timezoneId
integer		Timezone ID specifies data collection start time
dataCollectionMethodId
integer		static (1) collection period in a fixed set of dates
dynamic (2) data collection period over a rolling timeframe, with data refreshes every 24 hours
dataCollectionDays
integer		Number of days for data collection timeframe when data collection method is dynamic (maximum value: 30)
audienceSubTypes
integer		List of Audience Subtype IDs to further define the Contextual Audience
Response Properties
audienceIds
array of integers		Audience IDs
message
string		Success message
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"
  }
}

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.
  • If a subtype ID is passed, it must be valid for the vertical.
  • Data partners shown are based on active configurations.
Query Parameters
audienceTypeId
integer required		Audience Type ID
audienceSubtypeId
integer		Audience Subtype ID
verticalId
integer		Vertical ID
Response Properties
id
integer		Data partner ID
name
string		Data partner name
order
integer		Display order
displayName
string		Data partner display name
cpm
integer		Cost per mille (CPM)
logoUrl
string		URL to data partner logo
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"
    }
  ]
}

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
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+"
    }
  ]
}

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
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+"
    }
  ]
}

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
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"
        }
    ]
}

Audience Subtype List​

GET

Get a static list of Audience subtypes.

Query Parameter
audienceTypeIds
integer		Audience Type IDs
verticalId
integer		Vertical ID
Response Properties
id
integer		Audience subtype ID
name
string		Audience subtype name
order
integer		Order
displayName
string		Audience subtype display name
Response 200
{
  "success": true,
  "data": {
    "audienceSubtypes": [
      {
        "id": 3,
        "name": "hcp",
        "order": 3,
        "displayName": "HCP"
      },
      {
        "id": 4,
        "name": "npi_nurse",
        "order": 4,
        "displayName": "Nurse"
      },
      {
        "id": 5,
        "name": "non_npi_nurse",
        "order": 5,
        "displayName": "Non-NPI Nurse"
      },
      {
        "id": 6,
        "name": "patient",
        "order": 6,
        "displayName": "Patient"
      }
    ],
    "totalRecords": 4,
    "filteredRecords": 4
  }
}

Audience Status List​

GET

Get a static list of Audience statuses.

Query Parameter
audienceTypeIds
integer		Audience Type IDs
Response Properties
id
integer		Audience status ID
name
string		Status name
order
integer		Order
displayName
string		Audience status display name
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"
    }
]
}

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
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
    }
  ]
}
Have a question?
Ask the Community
Was this page helpful?