Skip to main content

Audience API

The Audience API allows you to create different types of Audiences for Healthcare Campaigns.

The following table describes some of the Audience types:

TypeDescription
Matched AudienceUpload a CSV or XLSX file with NPI numbers which is then matched with their respective digital entities to create a custom Audience segment for healthcare accounts.
ABM AudienceAccount-Based Marketing for healthcare Campaigns.

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

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

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

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

Healthcare Data Details​

ABM Audience Details​

GET

Get ABM Audience details by ID.

Path Parameter
audienceId
integer		ABM Audience ID
Response Properties
id
integer		Audience ID
name
string		Audience name
status
string		Audience status
audienceTypeId
integer		Audience Type ID
createdAt
integer		Unix epoch timestamp of Audience creation
partnerName
string		Partner name
partnerLogoUrl
string		Partner logo URL
uniques
integer		Count of unique Audiences reached
dataCost
integer		Fees charged by the platform if the Audience is used in any Campaign
filters
object		Frequency type
filter object properties
dataProviderIds
array of integers		Data Provider IDs
accountIds
array of integers		Account IDs
accountTypeIds
array of integers		Healthcare Account Type IDs
accountSubTypeIds
array of integers		Healthcare Account Subtype IDss
countryIds
array of integers		Country IDs
stateIds
array of integers		State IDs
cityIds
array of integers		City IDs
titleIds
array of integers		Title IDs
specialityIds
array of integers		Speciality IDs
ids
array of integers		IDs
pageNo
array of integers		Page number of retrieved data
noOfEntries
array of integers		Number of entries returned per page
Response 200
{
  "success": true,
  "data": {
    "id": 1124243,
    "name": "Test ABM audience",
    "status": "Processing",
    "audienceTypeId": 9,
    "createdAt": 1739261114,
    "partnerName": "Healthlink",
    "partnerLogoUrl": "www.sample.com",
    "uniques": 1000,
    "dataCost": 10,
    "healthCareDataMappingIds": [
      13572,
      13575,
      32777
    ],
    "filters": {
      "ids": [
        13572,
        13575,
        32777
      ],
      "dataProviderIds": [
        1
      ],
      "healthCareSystemIds": [
        1,
        2,
        3
      ],
      "accountIds": [
        1,
        2,
        3
      ],
      "accountTypeIds": [
        1,
        2,
        3
      ],
      "accountSubTypeIds": [
        1,
        2,
        3
      ],
      "titleIds": [
        1,
        2,
        3
      ],
      "specialityIds": [
        1,
        2,
        3
      ],
      "countryIds": [
        30100001
      ],
      "stateIds": [
        1,
        2,
        3
      ],
      "cityIds": [
        1,
        2,
        3
      ],
      "pageNo": 1,
      "noOfEntries": 10000
    }
  }
}

ABM Audience statistics​

GET

Get ABM Audience statistics by ID.

Path Parameter
audienceId
integer		ABM Audience ID
Response Properties
healthSystem
integer		Healthcare System ID
account
integer		Healthcare Account ID
accountType
integer		Healthcare Account Type ID
npiReach
integer		NPI reach
speciality
integer		Healthcare Specialty ID
Response 200
{
  "success": true,
  "data": {
    "healthSystem": 2,
    "account": 4,
    "accountType": 8,
    "npiReach": 25513,
    "speciality": 3
  }
}

Healthcare Titles List​

GET

Get a list of healthcare titles.

Query Parameters
dataProviderIds
array of integers		Data Provider IDs
pageNo
integer		Page number of retrieved data, default: 0
noOfEntries
integer		Number of entries returned per page, default: 50
searchField
string		Filter results by search field
Response Properties
id
integer		Title ID
displayName
string		Title name
displayOrder
integer		Display order
Response 200
{
  "success": true,
  "data": {
    "titleList": [
      {
        "id": 1,
        "displayName": "Healthcare Title 1",
        "displayOrder": 1
      },
      {
        "id": 2,
        "displayName": "Healthcare Title 2",
        "displayOrder": 20
      }
    ],
    "filteredRecords": 5,
    "totalRecords": 3294
  }
}

Healthcare Specialties List​

GET

Get a list of healthcare specialties.

Query Parameters
dataProviderIds
array of integers		Data Provider IDs
pageNo
integer		Page number of retrieved data, default: 0
noOfEntries
integer		Number of entries returned per page, default: 50
searchField
string		Filter results by search field
Response Properties
id
integer		Specialty ID
displayName
string		Specialty name
displayOrder
integer		Display order
Response 200
{
  "success": true,
  "data": {
    "specialityList": [
      {
        "id": 1,
        "displayName": "Healthcare Speciality 1",
        "displayOrder": 1
      },
      {
        "id": 2,
        "displayName": "Healthcare Speciality 2",
        "displayOrder": 20
      }
    ],
    "filteredRecords": 5,
    "totalRecords": 3294
  }
}

Healthcare Systems List​

GET

Get a list of healthcare systems.

Query Parameters
dataProviderIds
array of integers		Data Provider IDs
pageNo
integer		Page number of retrieved data, default: 0
noOfEntries
integer		Number of entries returned per page, default: 50
searchField
string		Filter results by search field
Response Properties
id
integer		System ID
displayName
string		System name
displayOrder
integer		Display order
Response 200
{
  "success": true,
  "data": {
    "healthcareSystemList": [
      {
        "id": 1,
        "displayName": "Healthcare System 1",
        "displayOrder": 1
      },
      {
        "id": 2,
        "displayName": "Healthcare System 2",
        "displayOrder": 20
      }
    ],
    "filteredRecords": 5,
    "totalRecords": 3294
  }
}

Healthcare Data​

POST

Get a healthcare data list by specified filters.

Query Parameters
dataProviderIds
array of integers		Data Provider IDs
pageNo
integer		Page number of retrieved data, default: 0
noOfEntries
integer		Number of entries returned per page, default: 50
healthCareSystemIds
array of integers 		Healthcare system IDs
accountNameIds
array of integers 		Account name IDs
accountTypeIds
array of integers 		Healthcare Account Type IDs
accountSubTypeIds
array of integers 		Account subtype IDs
countryIds
array of integers 		Country IDs
stateIds
array of integers 		State IDs
cityIds
array of integers 		City IDs
titleIds
array of integers 		Title IDs
specialityIds
array of integers 		Healthcare Specialty IDs
ids
array of integers 		IDs
Response Properties
id
integer		Audience ID
cost
integer		Charges for a specific segment
reach
integer		Unique reach of segments (i.e. Audience reach)
healthCareSystemId
integer		Healthcare System ID
healthCareSystemName
string		Healthcare System name
accountId
integer		Healthcare Account ID
accountName
string		Healthcare account name
accountTypeId
integer		Healthcare Account Type ID
accountTypeName
string		Healthcare Account type name
accountSubTypeId
integer		Healthcare Account Subtype ID
accountSubTypeName
string		Healthcare Account subtype name
titleId
integer		Healthcare Title ID
titleName
string		Healthcare title name
specialityId
integer		Healthcare Specialty ID
specialityName
string		Healthcare specialty name
countryId
integer		Country ID
countryName
string		Country name
stateId
integer		State ID
stateName
string		State name
cityId
integer		City ID
cityName
string		City name
dataProviderId
integer		Data Provider ID
dataProviderName
string		Data provider name
Request Sample
{
  "dataProviderIds": [
    1
  ],
  "healthCareSystemIds": [
    40100004,
    40100007
  ],
  "accountIds": [
    40208104,
    40628423
  ],
  "accountTypeIds": [
    40300003
  ],
  "accountSubTypeIds": [
    40400001,
    40400010
  ],
  "countryIds": [
    30100001
  ],
  "stateIds": [
    30200028,
    30200043
  ],
  "cityIds": [
    30430356,
    30447825,
    30447952,
    30448122
  ],
  "titleIds": [
    40500099
  ],
  "specialityIds": [
    40500014,
    40500086
  ],
  "ids": [
    1,
    2,
    3
  ],
  "pageNo": 1,
  "noOfEntries": 2
}
Response 200
{
  "success": true,
  "data": {
    "totalRecords": 52265,
    "filteredRecords": 5,
    "healthCareData": [
      {
        "id": 1,
        "cost": 10,
        "reach": 1,
        "healthCareSystemId": 40100004,
        "healthCareSystemName": "ABCD PEDIATRICS",
        "accountId": 40628423,
        "accountName": "Stepping Stone Pediatrics PA",
        "accountTypeId": 40300003,
        "accountTypeName": "Group Practice",
        "accountSubTypeId": 40400010,
        "accountSubTypeName": "Telephone/E-Mail Order Pharmacy",
        "titleId": 40500099,
        "titleName": "MD",
        "specialityId": 40500086,
        "specialityName": "Gastroenterology",
        "countryId": 30100001,
        "countryName": "United States",
        "stateId": 30200043,
        "stateName": "Tennessee",
        "cityId": 30447952,
        "cityName": "Franklin, TN",
        "dataProviderId": 1,
        "dataProviderName": "HealthCarelink"
      },
      {
        "id": 2,
        "cost": 10,
        "reach": 1,
        "healthCareSystemId": 40100004,
        "healthCareSystemName": "ABCD PEDIATRICS",
        "accountId": 40628423,
        "accountName": "Stepping Stone Pediatrics PA",
        "accountTypeId": 40300003,
        "accountTypeName": "Group Practice",
        "accountSubTypeId": 40400010,
        "accountSubTypeName": "Telephone/E-Mail Order Pharmacy",
        "titleId": 40500099,
        "titleName": "MD",
        "specialityId": 40500086,
        "specialityName": "Gastroenterology",
        "countryId": 30100001,
        "countryName": "United States",
        "stateId": 30200043,
        "stateName": "Tennessee",
        "cityId": 30447825,
        "cityName": "Brentwood, TN",
        "dataProviderId": 1,
        "dataProviderName": "HealthCarelink"
      }
    ]
  }
}

Healthcare Statistics​

POST

Get healthcare statistics details.

Query Parameters
dataProviderIds
array of integers		Data Provider IDs
pageNo
integer		Page number of retrieved data, default: 0
noOfEntries
integer		Number of entries returned per page, default: 50
healthCareSystemIds
array of integers 		Healthcare system IDs
accountNameIds
array of integers 		Account name IDs
accountTypeIds
array of integers 		Healthcare Account Type IDs
accountSubTypeIds
array of integers 		Account subtype IDs
countryIds
array of integers 		Country IDs
stateIds
array of integers 		State IDs
cityIds
array of integers 		City IDs
titleIds
array of integers 		Title IDs
specialityIds
array of integers 		Healthcare Specialty IDs
ids
array of integers 		IDs
Response Properties
healthSystem
integer		Healthcare System ID
account
integer		Healthcare Account ID
accountType
integer		Healthcare Account Type ID
npiReach
integer		NPI reach
speciality
integer		Healthcare Specialty ID
Request Sample
{
  "dataProviderIds": [
    1
  ],
  "healthCareSystemIds": [
    40100004,
    40100007
  ],
  "accountIds": [
    40208104,
    40628423
  ],
  "accountTypeIds": [
    40300003
  ],
  "accountSubTypeIds": [
    40400001,
    40400010
  ],
  "countryIds": [
    30100001
  ],
  "stateIds": [
    30200028,
    30200043
  ],
  "cityIds": [
    30430356,
    30447825,
    30447952,
    30448122
  ],
  "titleIds": [
    40500099
  ],
  "specialityIds": [
    40500014,
    40500086
  ],
  "ids": [
    1,
    2,
    3
  ],
  "pageNo": 1,
  "noOfEntries": 2
}
Response 200
{
  "success": true,
  "data": {
    "healthSystem": 2,
    "account": 4,
    "accountType": 8,
    "npiReach": 25513,
    "speciality": 3
  }
}

Healthcare Account Types​

POST

Get a list of healthcare account types.

Query Parameters
dataProviderIds
array of integers		Data Provider IDs
pageNo
integer		Page number of retrieved data, default: 0
noOfEntries
integer		Number of entries returned per page, default: 50
healthCareSystemIds
array of integers 		Healthcare system IDs
accountNameIds
array of integers 		Account name IDs
searchField
string		Filter results by search field
Response Properties
id
integer		Account ID
displayName
string		Account name
displayOrder
integer		Display order
Request Sample
{
  "pageNo": 1,
  "noOfEntries": 20,
  "searchField": "Sample Text",
  "dataProviderIds": [
    1
  ],
  "healthcareSystemIds": [
    1,
    2,
    3
  ],
  "accountNameIds": [
    4,
    5,
    6
  ]
}
Response 200
{
  "success": true,
  "data": {
    "accountTypeList": [
      {
        "id": 1,
        "displayName": "Account Type 1",
        "displayOrder": 1
      },
      {
        "id": 2,
        "displayName": "Account Type 2",
        "displayOrder": 2
      }
    ],
    "filteredRecords": 5,
    "totalRecords": 3294
  }
}

Healthcare Account Subtypes​

POST

Get a list of healthcare account subtypes.

Query Parameters
dataProviderIds
array of integers		Data Provider IDs
pageNo
integer		Page number of retrieved data, default: 0
noOfEntries
integer		Number of entries returned per page, default: 50
healthCareSystemIds
array of integers 		Healthcare system IDs
accountNameIds
array of integers 		Account name IDs
searchField
string		Filter results by search field
accountTypeIds
array of integers 		Healthcare Account Type IDss
Response Properties
id
integer		Account subtype ID
displayName
string		Account sub name
displayOrder
integer		Display order
Request Sample
{
  "pageNo": 1,
  "noOfEntries": 20,
  "searchField": "Sample Text",
  "dataProviderIds": [
    1
  ],
  "healthcareSystemIds": [
    1,
    2,
    3
  ],
  "accountNameIds": [
    4,
    5,
    6
  ],
  "accountTypeIds": [
    7,
    8,
    9
  ]
}
Response 200
{
  "success": true,
  "data": {
    "accountSubTypeList": [
      {
        "id": 1,
        "displayName": "Account Subtype 1",
        "displayOrder": 1
      },
      {
        "id": 2,
        "displayName": "Account Subtype 2",
        "displayOrder": 2
      }
    ],
    "filteredRecords": 5,
    "totalRecords": 3294
  }
}

Healthcare Account Names​

POST

Get a list of healthcare account names.

Query Parameters
dataProviderIds
array of integers		Data Provider IDs
pageNo
integer		Page number of retrieved data, default: 0
noOfEntries
integer		Number of entries returned per page, default: 50
healthCareSystemIds
array of integers 		Healthcare system IDs
searchField
string		Filter results by search field
Response Properties
id
integer		Account name ID
displayName
string		Account name
displayOrder
integer		Display order
Request Sample
{
  "pageNo": 1,
  "noOfEntries": 20,
  "searchField": "Sample text",
  "dataProviderIds": [
    1
  ],
  "healthcareSystemIds": [
    1,
    2,
    3
  ]
}
Response 200
{
  "success": true,
  "data": {
    "accountNameList": [
      {
        "id": 1,
        "displayName": "Account Name 1",
        "displayOrder": 1
      },
      {
        "id": 2,
        "displayName": "Account Name 2",
        "displayOrder": 20
      }
    ],
    "filteredRecords": 5,
    "totalRecords": 3294
  }
}

Create ABM Audience​

POST

Create an ABM Audience.

Request Schema
audienceName
string		Audience name
healthCareDataMappingIds
array of integers		Frequency
dataProviderId
integer		Data provider ID
filters
object		Filters
filter object properties
dataProviderIds
array of integers		Data Provider IDs
accountIds
array of integers		Account IDs
accountTypeIds
array of integers		Healthcare Account Type IDs
accountSubTypeIds
array of integers		Healthcare Account Subtype IDss
countryIds
array of integers		Country IDs
stateIds
array of integers		State IDs
cityIds
array of integers		City IDs
titleIds
array of integers		Title IDs
specialityIds
array of integers		Specialty IDs
ids
array of integers		IDs
pageNo
array of integers		Page number of retrieved data
noOfEntries
array of integers		Number of entries returned per page
Response Properties
message
string		Success message
Request Sample
{
  "audienceName": "HealthCare Innovators",
  "healthCareDataMappingIds": [
    1,
    2,
    3
  ],
  "dataProviderId": 1,
  "filters": {
    "dataProviderIds": [
      1
    ],
    "healthCareSystemIds": [
      40100004,
      40100007
    ],
    "accountIds": [
      40208104,
      40628423
    ],
    "accountTypeIds": [
      40300003
    ],
    "accountSubTypeIds": [
      40400001,
      40400010
    ],
    "countryIds": [
      30100001
    ],
    "stateIds": [
      30200028,
      30200043
    ],
    "cityIds": [
      30430356,
      30447825,
      30447952,
      30448122
    ],
    "titleIds": [
      40500099
    ],
    "specialityIds": [
      40500014,
      40500086
    ],
    "ids": [
      1,
      2,
      3
    ],
    "pageNo": 1,
    "noOfEntries": 2
  }
}
Response 200
{
  "success": true,
  "data": {
    "message": "HealthCare Innovators audience created successfully"
  }
}

Geofarmed Audiences​

Geofarmed Audience Details​

GET

Get Geofarmed Audience Details by ID.

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

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

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

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