Audience Insights

  • Article

Warning

Deprecation Notice
The Marketing version 202304 (Marketing April 2023) and below has been sunset and the unversioned APIs are going to 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.

Try in Postman

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_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:

    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:

    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