Audience Insights
Warning
Deprecation Notice
The Marketing Version 202310 (Marketing October 2023) and earlier versions (excluding 202306 and 202307) have been sunset. Additionally, the unversioned APIs will be sunset soon. We recommend that you migrate to the versioned APIs as well as migrate to the new Content and Community Management APIs to avoid disruptions. See the Migration page for more details.
If you haven’t yet migrated and have questions, submit a request on the LinkedIn Developer Support Portal.
Overview
Audience Insights API enables you to discover and identify the audience segments that meet your target persona, demonstrate interest and engagement in relevant customer products/offerings, uncover insights about the companies the target audience works for, and activate audience for targeting in sponsored ad campaigns on LinkedIn. This enables advertisers to use LinkedIn data and insights as a part of their broader audience discovery, planning, activation and optimization processes by delivering on the “Audience first” approach.
Audience Insights API provides aggregated demographic insights, firmographic details, location and interests / behaviors of a target audience. The insights are primarily comprised of the below categories :
- Member Insights (Job Function, Title, Seniority, Years Of Experience, Skills)
- Company Insights (Company Name, Industry, Size, Growth rate)
- Location Insights (City, State, Country/Region, Continent)
- Member Interests (General and Product Interest categories derived from engagement behaviors and profile information)
Note
This is a private API that is available to qualified developers who meet additional criteria for access. To learn more about eligibility qualifications and how to request access, please see the FAQ. If you wish to apply for access, please submit a Zendesk support ticket.
Permissions
Audience Insights API requires a 3-legged OAuth member token and your developer application needs to be provisioned with the Audience Insights API product. Once you have been approved to access, you can use any valid member access token associated with the authenticated user with any valid scope permissions for member authentication. If there is no valid member token for the relevant user from any previous integration, we recommend using the bare minimum scope permissions like r_ads which will be required to fetch authenticated user's ad accounts.
Note
This API is application-specific; hence, explicit member consent is not required. Any valid member access token associated with the authenticated user can be used, and you do not need to add any additional permission in the scope of your Oauth2 flow for authorization.
Request Schema
| Field | Type | Description | Required |
|---|---|---|---|
| request | request Object | request Object that wraps the entire request body. See details below. | Yes |
request Object
| Field | Type | Description | Required |
|---|---|---|---|
| requestMetaData | requestMetaData Object | requestMetaData Object with sponsoredAccountUrn to identify the sponsored ad account where the authenticated user has a valid user role. See details below. |
Yes |
| targetingCriteria | targetingCriteria Object | targetingCriteria Object defines the audience that the desired insights are for. This is a boolean expression of ad targeting facets and entities that identifies the member attributes to be included/excluded in the audience. See details below. | Yes |
| groupBy | AdTargetingFacetURN | The ad targeting facet for which the provided audience criteria should be segmented for insights in the response. | Yes |
| segmentsOrderedBy | string (Enum) | The order in which the segments should be returned. By default, the segments will be ordered in the descending order of the audience percentage of segments. Available values are: AUDIENCE_PERCENTAGE : Based on DESC order of Audience Percentage. HIERARCHICAL : Based on the hierarchical order of urns. This is supported only for a select few low cardinality facets like YearsOfExperience, Company Size, etc. |
Optional (default=AUDIENCE_PERCENTAGE) |
| maxReturnCount | int | The max number of segments to include in the response. Default is 5 and maximum is 100. | Optional (default=5) |
requestMetaData Object
The requestMetaData Object requires a sponsoredAccountUrn, where the authenticated user must be assigned a valid ad account user role.
| Field | Type | Description | Required |
|---|---|---|---|
| sponsoredAccountUrn | URN | The sponsored ad account URN where the authenticated user has a valid ad account user role. | Yes |
Ad Account User Roles:
ACCOUNT_BILLING_ADMINACCOUNT_MANAGERCAMPAIGN_MANAGERCREATIVE_MANAGERVIEWER
To make a request on behalf of a given user, you should fetch that authenticated user’s ad accounts and select one of their ad accounts. Refer Find Ad Accounts By Authenticated User to find and select an ad account.
For more information on Ad Account roles and permissions:
targetingCriteria Object
targetingCriteria provides a generic AND / OR construct to include and exclude different adTargetingFacets when defining the audience. The targeting criteria can be composed of LinkedIn Audience Attributes and/or existing matched audience Ad Segments (Contact/Company lists). See Ad Segments to fetch existing matched audience ad segment URNs that can be passed to urn:li:adTargetingFacet:audienceMatchingSegments.
The basic structure for a targetingCriteria object is as follows:
{
"targetingCriteria":{
"include":{
"and":[
{
"or":{
"urn:li:adTargetingFacet:{facet1}":[
"{facet1_value1}",
"{facet1_value2}"
],
"urn:li:adTargetingFacet:{facet2}":[
"{facet2_value1}"
]
}
},
{
"or":{
"urn:li:adTargetingFacet:{facet3}":[
"{facet3_value1}",
"{facet3_value2}"
]
}
}
]
},
"exclude":{
"or":{
"urn:li:adTargetingFacet:{facet4}":[
"{facet4_value1}"
]
}
}
}
}
Refer the below links for additional details:
- targetingCriteria object
- Descriptive examples for targetingCriteria object
- List of supported adTargetingFacets in targetingCriteria object
- Ad Targeting Entities
Supported adTargetingFacets for groupBy Field
This list outlines the available adTargetingFacets in groupBy field to derive insights from the target audience segmented by one of these facets in response.
| Facet Urn | Facet Name |
|---|---|
| urn:li:adTargetingFacet:jobFunctions | Job Functions |
| urn:li:adTargetingFacet:seniorities | Job Seniorities |
| urn:li:adTargetingFacet:titles | Job Titles |
| urn:li:adTargetingFacet:yearsOfExperienceRanges | Years Of Experience |
| urn:li:adTargetingFacet:interests | Member Interests |
| urn:li:adTargetingFacet:productInterests | Member Product Interests |
| urn:li:adTargetingFacet:skills | Member Skills |
| urn:li:adTargetingFacet:industries | Company Industries |
| urn:li:adTargetingFacet:staffCountRanges | Company Size |
| urn:li:adTargetingFacet:growthRate | Company Growth Rate |
| urn:li:adTargetingFacet:employers | Company Names |
| urn:li:adTargetingFacet:bingContinent | Member's continent level locations |
| urn:li:adTargetingFacet:bingCountry | Member's country/region level locations |
| urn:li:adTargetingFacet:bingCity | Member's city level locations |
| urn:li:adTargetingFacet:bingState | Member's state level locations |
Validations and Minimum Requirements
- You must provide a sponsored ad account ID in the request metadata. Authenticated member must have access to that sponsored ad account (any role VIEWER or above).
- The Targeting Criteria provided in the request should have a geo or profileGeo, and a second targeting attribute other than age, gender, or language.
- A Targeting Criteria with a matched audience or a dynamic segment does not require additional targeting attributes (like geo) to be included with it.
- The total audience count for the Targeting Criteria provided should be at least 300 but less than 100M.
- If the audience size of the targeting criteria provided in the request is less than 300, an empty response with the audience count 0 will be returned.
- If the audience size of the targeting criteria provided in the request is larger than 100M, an empty response with an approximate total audience count will be returned.
- A segment will not be returned in the response if the audience count for the segment is less than 30.
- Certain combinations of ad targeting facets are not supported in targeting criteria inclusion. For example, Seniorities may not be AND'ed with any "include" clauses targeting Job Titles.
Sample Request
Note
All API requests are represented in Rest.li Protocol 2.0.0 and require the header: X-Restli-Protocol-Version: 2.0.0. Read the Protocol Versions document to learn about using Rest.li Protocol 2.0.0.
POST https://api.linkedin.com/rest/targetingAudienceInsights?action=audienceInsights
{
"request":{
"requestMetaData": {
"sponsoredAccount": "urn:li:sponsoredAccount:123"
},
"targetingCriteria":{
"include":{
"and":[
{
"or":{
"urn:li:adTargetingFacet:locations":[
"urn:li:geo:105080838"
]
}
},
{
"or":{
"urn:li:adTargetingFacet:interfaceLocales":[
"urn:li:locale:en_US"
]
}
},
{
"or":{
"urn:li:adTargetingFacet:skills":[
"urn:li:skill:236",
"urn:li:skill:242",
"urn:li:skill:252"
]
}
}
]
}
},
"groupBy": "urn:li:adTargetingFacet:jobFunctions",
"maxReturnCount" : 5
}
}
Response Schema
| Field Name | Type | Description |
|---|---|---|
| audienceInsight | audienceInsight object | Audience Insight object which gives a breakdown of the audience in the request into segments grouped by the selected ad facet. |
| totalAudienceCount | long | The full audience count of the base audience provided in the request, which can be used to calculate percentages from the segmentations. |
audienceInsight Object
| Field Name | Type | Description |
|---|---|---|
| groupedBy | AdTargetingFacetUrn | The ad facet for which the audience is sliced by. This field contains the ad facet urn; the same as the urn of the AdTargetingEntity element of the facets array. |
| segmentations | array [segmentations object] | An array of segments and corresponding metric data that shows insights for a slice of this audience. |
segmentations Object
| Field Name | Type | Description |
|---|---|---|
| entityCount | long | The entity count for this segment. |
| entityPercentage | int | The percentage of the selected audience that's represented by this segment, calculated by dividing its entityCount by the totalEntityCount and then times 100 to be converted to an integer. The range of this field is between 0 to 100. |
| value | AdTargetingEntityUrn | A single segment value of the facet for which the results are grouped by. This field contains the segment urn, which is the same as the urn of the AdTargetingEntity element of the segments array. |
Sample Response
{
"value": {
"audienceInsight": {
"segmentations": [
{
"entityCount": 96000,
"entityPercentage": 23,
"value": "urn:li:function:4"
},
{
"entityCount": 61000,
"entityPercentage": 15,
"value": "urn:li:function:20"
},
{
"entityCount": 55000,
"entityPercentage": 13,
"value": "urn:li:function:18"
},
{
"entityCount": 40000,
"entityPercentage": 10,
"value": "urn:li:function:13"
},
{
"entityCount": 31000,
"entityPercentage": 7,
"value": "urn:li:function:5"
}
],
"groupedBy": "urn:li:adTargetingFacet:jobFunctions"
},
"totalAudienceCount": 420000
}
}
Once you have fetched the desired insights, you can save the targeting criteria used to fetch insights with the Saved Audience Templates API, so that you can activate them through the campaign API or from the Campaign Manager User Interface.
API Error Details
| HTTP Status Code | ERROR MESSAGE | DESCRIPTION | ERROR RESOLUTION |
|---|---|---|---|
| 401 | EMPTY_ACCESS_TOKEN | Empty or expired oauth2 access token | Use a valid member access token |
| 403 | ACCESS_DENIED | Not enough permissions to access: targetingAudienceInsights | Make sure you developer application is provisioned with the (Private) Audience Insights API |
| 403 | USER_NOT_AUTHORIZED | Caller should have access to the Ad Account provided in the request | Make sure the member associated with access token has a user role on the provided Ad Account |
| 422 | FAILED_VALIDATION_CONDITION | Request fails structure validation. / Missing required fields in the request | Make sure all required fields are passed and follow valid structure |
| 500 | INTERNAL_SERVER_ERROR | Internal server side error | N/A |