Audience Insights

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)

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.

Request Schema

request Object

requestMetaData Object

The requestMetaData Object requires a sponsoredAccountUrn, where the authenticated user must be assigned a valid ad account user role.

Ad Account User Roles:

• ACCOUNT_BILLING_ADMIN
• ACCOUNT_MANAGER
• CAMPAIGN_MANAGER
• CREATIVE_MANAGER
• VIEWER

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:

• Ad Account User Role Definitions
• Create and Manage Ad Account Users

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.

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

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

curl -X POST 'https://api.linkedin.com/rest/targetingAudienceInsights?action=audienceInsights' \
-H 'Authorization: Bearer {INSERT_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'X-RestLi-Protocol-Version:2.0.0'\
-H 'Linkedin-Version:{yyyyMM}'\
--data '
{ 
 "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

audienceInsight Object

segmentations Object

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