Ad Targeting

  • 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

Try in Postman

LinkedIn's Ad Targeting API enables advertisers to better control which audiences see their ads. These controls include a variety of member demographics in the LinkedIn platform. Targeting is set at the campaign level, and applies to all creatives associated with that campaign.

The two core concepts for targeting are facets and entities.

Facets are high-level categories of the types of targeting available to you. Facets contain multiple entities which are the specific demographic values within that facet.

For example, Industries is a facet. Specific industries such as Computer Software, Biotechnology, and Telecommunications are entities within the Industries facet.

Permissions

Any application approved for the LinkedIn Marketing API Program can make these API calls using any 3-legged access token. No additional permissions need to be requested during the OAuth flow.

Targeting Discrimination Notice

Applications utilizing LinkedIn's targeting capabilities are required to display a notice in their user interface notifying advertisers that they cannot use LinkedIn to discriminate against members based on personal characteristics. The notice should include the following text:

LinkedIn tools may not be used to discriminate based on personal characteristics like gender, age, race, or ethnicity. Learn more.

To learn more about targeting in general on LinkedIn, see Targeting Optionsand Best Practices for LinkedIn Advertisements.

Ad Targeting Facets

Facets are high-level categories of the types of targeting available to you. Use facets to narrow down your intended audience. Refer to Targeting Criteria Facet URNs for the list of available facets and their URNs.

The adTargetingFacets API returns available targeting facets.

Sample Request

To add new fields or enums to an existing schema:

GET https://api.linkedin.com/rest/adTargetingFacets

GET https://api.linkedin.com/v2/adTargetingFacets

Sample Response

The response returns facets available to you for targeting. Each targeting type contains the name of the facet, the type, and Finder methods to get more information on the type and values.

To learn more, see the Ad Targeting Facets API.

{ 
   "elements":[ 
      {
         "facetName":"genders",
         "availableEntityFinders":[ 
            "AD_TARGETING_FACET"
          ],
         "entityTypes":[ 
            "GENDER"
          ],
         "adTargetingFacetUrn":"urn:li:adTargetingFacet:genders"
       },
      {
         "facetName":"industries",
         "availableEntityFinders":[ 
            "AD_TARGETING_FACET",
            "TYPEAHEAD",
            "SIMILAR_ENTITIES"
          ],
         "entityTypes":[ 
            "INDUSTRY"
          ],
         "adTargetingFacetUrn":"urn:li:adTargetingFacet:industries"
       },
      ... some facets omitted ...
      { 
         "facetName":"memberBehaviors",
         "availableEntityFinders":[ 
            "AD_TARGETING_FACET",
            "TYPEAHEAD"
          ],
         "entityTypes":[ 
            "MEMBER_BEHAVIOR"
          ],
         "adTargetingFacetUrn":"urn:li:adTargetingFacet:memberBehaviors"
       },
      { 
         "facetName":"growthRate",
         "availableEntityFinders":[ 
            "AD_TARGETING_FACET",
            "TYPEAHEAD"
          ],
         "entityTypes":[ 
            "FIRMOGRAPHIC"
          ],
         "adTargetingFacetUrn":"urn:li:adTargetingFacet:growthRate"
       },
      { 
         "facetName":"companyCategory",
         "availableEntityFinders":[ 
            "AD_TARGETING_FACET",
            "TYPEAHEAD"
          ],
         "entityTypes":[ 
            "FIRMOGRAPHIC"
          ],
         "adTargetingFacetUrn":"urn:li:adTargetingFacet:companyCategory"
       }
    ]
}

{ 
   "elements":[ 
      {
         "facetName":"genders",
         "availableEntityFinders":[ 
            "AD_TARGETING_FACET"
          ],
         "entityTypes":[ 
            "GENDER"
          ],
         "$URN":"urn:li:adTargetingFacet:genders"
       },
      {
         "facetName":"industries",
         "availableEntityFinders":[ 
            "AD_TARGETING_FACET",
            "TYPEAHEAD",
            "SIMILAR_ENTITIES"
          ],
         "entityTypes":[ 
            "INDUSTRY"
          ],
         "$URN":"urn:li:adTargetingFacet:industries"
       },
      ... some facets omitted ...
      { 
         "facetName":"memberBehaviors",
         "availableEntityFinders":[ 
            "AD_TARGETING_FACET",
            "TYPEAHEAD"
          ],
         "entityTypes":[ 
            "MEMBER_BEHAVIOR"
          ],
         "$URN":"urn:li:adTargetingFacet:memberBehaviors"
       },
      { 
         "facetName":"growthRate",
         "availableEntityFinders":[ 
            "AD_TARGETING_FACET",
            "TYPEAHEAD"
          ],
         "entityTypes":[ 
            "FIRMOGRAPHIC"
          ],
         "$URN":"urn:li:adTargetingFacet:growthRate"
       },
      { 
         "facetName":"companyCategory",
         "availableEntityFinders":[ 
            "AD_TARGETING_FACET",
            "TYPEAHEAD"
          ],
         "entityTypes":[ 
            "FIRMOGRAPHIC"
          ],
         "$URN":"urn:li:adTargetingFacet:companyCategory"
       }
    ]
}

Ad Targeting Entities

Once you've identified the facet type(s) you'd like to target, you can fetch their entity values.

Use the adTargetingEntities API to fetch available options for each facet type. To learn more, see Ad Targeting Entities.

Find Entities by Facet

This method returns targeting entities contained within a given targeting facet. For example, passing in the industries targeting facet will return names and URNs for all the industry targeting entities.

GET https://api.linkedin.com/rest/adTargetingEntities?q=adTargetingFacet&facet={encoded adTargetingFacet URN}

GET https://api.linkedin.com/v2/adTargetingEntities?q=adTargetingFacet&facet={adTargetingFacet URN}

Parameters

Field Name Required Type Description
q Yes String This field should always be adTargetingFacet for this method.
facet Yes adTargetingFacet URN Targeting facet that results should be returned for.
locale.language No String A lowercase two-letter language code as defined by ISO-639. Defaults to "en" if no value is provided.
locale.country No String An uppercase two-letter country code as defined by ISO-3166. Defaults to "US" if no value is provided.
queryVersion No String This field should always be QUERY_USES_VALUES.

Sample Request

GET https://api.linkedin.com/rest/adTargetingEntities?q=adTargetingFacet&queryVersion=QUERY_USES_URNS&facet=urn%3Ali%3AadTargetingFacet%3Aseniorities&locale=(language:en,country:US)

GET https://api.linkedin.com/v2/adTargetingEntities?q=adTargetingFacet&queryVersion=QUERY_USES_URNS&facet=urn:li:adTargetingFacet:seniorities&locale.language=en&locale.country=US

Sample Response

{
    "elements": [
        {
            "urn": "urn:li:seniority:1",
            "facetUrn": "urn:li:adTargetingFacet:seniorities",
            "name": "Unpaid"
        },
        {
            "urn": "urn:li:seniority:10",
            "facetUrn": "urn:li:adTargetingFacet:seniorities",
            "name": "Owner"
        },
        {
            "urn": "urn:li:seniority:2",
            "facetUrn": "urn:li:adTargetingFacet:seniorities",
            "name": "Training"
        },
        {
            "urn": "urn:li:seniority:3",
            "facetUrn": "urn:li:adTargetingFacet:seniorities",
            "name": "Entry"
        },
        {
            "urn": "urn:li:seniority:4",
            "facetUrn": "urn:li:adTargetingFacet:seniorities",
            "name": "Senior"
        },
    ..
    ]
}

Ad Targeting Entities for Member Behaviors

GET https://api.linkedin.com/rest/adTargetingEntities?q=adTargetingFacet&facet=urn%3Ali%3AadTargetingFacet%3AmemberBehaviors&queryVersion=QUERY_USES_URNS&locale=(language:en,country:US)

GET https://api.linkedin.com/v2/adTargetingEntities?q=adTargetingFacet&facet=urn:li:adTargetingFacet:memberBehaviors&locale.language=en&locale.country=US&queryVersion=QUERY_USES_URNS

Sample Response

{
    "elements": [
       {
            "urn": "urn:li:memberBehavior:2",
            "facetUrn": "urn:li:adTargetingFacet:memberBehaviors",
            "name": "Mobile Users"
        },
        {
            "urn": "urn:li:memberBehavior:3",
            "facetUrn": "urn:li:adTargetingFacet:memberBehaviors",
            "name": "iPhone Users",
        },
        ... Some entities omitted ...
        {
            "urn": "urn:li:memberBehavior:13",
            "facetUrn": "urn:li:adTargetingFacet:memberBehaviors",
            "name": "Open to Education",
        },
        {
            "urn": "urn:li:memberBehavior:14",
            "facetUrn": "urn:li:adTargetingFacet:memberBehaviors",
            "name": "Frequent Contributor",
        }
    ],
    "paging": {
        "count": 2147483647,
        "start": 0,
        "links": []
    }
}

Ad Targeting Entities for Company Growth Rate and Category

LinkedIn now enables advertisers to include company growth rate and company category to target LinkedIn members by.

Sample Request

GET https://api.linkedin.com/rest/adTargetingEntities?facet=urn%3Ali%3AadTargetingFacet%3AcompanyCategory&q=adTargetingFacet&queryVersion=QUERY_USES_URNS&totals=false

GET https://api.linkedin.com/v2/adTargetingEntities?facet=urn%3Ali%3AadTargetingFacet%3AcompanyCategory&q=adTargetingFacet&queryVersion=QUERY_USES_URNS&totals=false

Sample Response

  {
    "elements": [
        {
            "urn": "urn:li:organizationRankingList:1",
            "facetUrn": "urn:li:adTargetingFacet:companyCategory",
            "name": "Fortune Global 500",
        },
     // ... Some entities omitted ...
        {
             "urn": "urn:li:organizationRankingList:3",
            "facetUrn": "urn:li:adTargetingFacet:companyCategory",
            "name": "Forbes World's Most Innovative Companies",
        }
    ],
    "paging": {
        "count": 2147483647,
        "start": 0,
        "links": []
    }

Find Entities by Similar Entities

This method returns targeting entities that are similar to a given targeting entity. For example, passing in the employers targeting facet and an organization URN for a university would return name and URNs of similar employers. In this case, the similar employers would be other universities.

The number of entities per facet is capped to 100 for nearly all facets. The exceptions are employers, employersPast, employersAll, geos, and profileGeos which are capped to 200. To target a larger audience, see Audiences.

GET https://api.linkedin.com/rest/adTargetingEntities?q=similarEntities&facet={facetURN}&entities=List({encoded URN1},{encoded URN2})

GET https://api.linkedin.com/v2/adTargetingEntities?q=similarEntities&facet={facetURN}&entities={URN}

Parameters

Field Name Required Type Description
q Yes String This field should always be similarEntities for this method.
facet Yes adTargetingFacet URN Targeting facet that results should be returned for.
entities Yes Array of URNs URNs of the entities that will be use to retrieve similar entities for.
entityType No String Enum to restrict results to only contain data that matches type requested. Possible values:
  • AGE
  • COMPANY
  • COMPANY_SIZE
  • DEGREE
  • FIELD_OF_STUDY
  • FUNCTION
  • GENDER
  • GROUP
  • INDUSTRY
  • LOCALE
  • SCHOOL
  • SENIORITY
  • SKILL
  • TITLE
  • YEARS_OF_EXPERIENCE
locale.language No String A lowercase two-letter language code as defined by ISO-639. Defaults to "en" if no value is provided.
locale.country No String An uppercase two-letter country code as defined by ISO-3166. Defaults to "US" if no value is provided.
queryVersion No String This field should always be QUERY_USES_URNS.

Sample Request

This example shows how to discover similar employers by passing in an organization URN.

GET https://api.linkedin.com/rest/adTargetingEntities?q=similarEntities&facet=urn%3Ali%3AadTargetingFacet%3Aemployers&queryVersion=QUERY_USES_URNS&entities=List(urn%3Ali%3Aorganization%3A1003)&locale=(language:en,country:US)

GET https://api.linkedin.com/v2/adTargetingEntities?q=similarEntities&facet=urn:li:adTargetingFacet:employers&queryVersion=QUERY_USES_URNS&entities=urn:li:organization:1003&locale.language=en&locale.country=US

Sample Response

{
    "elements": [
        {
            "urn": "urn:li:organization:163361",
            "facetUrn": "urn:li:adTargetingFacet:employers",
            "name": "DataMirror"
        },
        {
            "urn": "urn:li:organization:1666",
            "facetUrn": "urn:li:adTargetingFacet:employers",
            "name": "Intuit"
        },
        {
            "urn": "urn:li:organization:10715",
            "facetUrn": "urn:li:adTargetingFacet:employers",
            "name": "Lexmark Enterprise Software"
        },
        {
            "urn": "urn:li:organization:21867",
            "facetUrn": "urn:li:adTargetingFacet:employers",
            "name": "eClinicalWorks"
        }
    ],
    "paging": {
        "total": 48,
        "count": 2147483647,
        "start": 0,
        "links": []
    }
}

Find Entities by Typeahead

This method allows search of targeting entities within a given targeting facet.

GET https://api.linkedin.com/rest/adTargetingEntities?q=typeahead&facet={encoded adTargetingFacet URN}&query={Search Query}

GET https://api.linkedin.com/v2/adTargetingEntities?q=typeahead&facet={adTargetingFacet URN}&query={Search Query}

Parameters

Field Name Required Type Description
q Yes String This field should always be TYPEAHEAD for this method.
facet Yes adTargetingFacet URN Targeting facet that results should be returned for.
query Yes String String of partial text to be used for matching with.
entityType No String Enum to restrict results to only contain data that matches type requested. Possible values:
  • AGE
  • COMPANY
  • COMPANY_SIZE
  • DEGREE
  • FIELD_OF_STUDY
  • FUNCTION
  • GENDER
  • GROUP
  • INDUSTRY
  • INTEREST
  • LOCALE
  • SCHOOL
  • SENIORITY
  • SKILL
  • TITLE
  • YEARS_OF_EXPERIENCE
  • MEMBER_BEHAVIOR
locale.language No String A lowercase two-letter language code as defined by ISO-639. Defaults to "en" if no value is provided.
locale.country No String An uppercase two-letter country code as defined by ISO-3166. Defaults to "US" if no value is provided.
queryVersion No String This field should always be QUERY_USES_URNS.

Sample Request: GET Fields of Study Entities for 'Economics'

GET https://api.linkedin.com/rest/adTargetingEntities?q=typeahead&entityType=FIELD_OF_STUDY&queryVersion=QUERY_USES_URNS&facet=urn%3Ali%3AadTargetingFacet%3AfieldsOfStudy&query=econ&locale=(language:en,country:US)

GET https://api.linkedin.com/v2/adTargetingEntities?q=typeahead&entityType=FIELD_OF_STUDY&queryVersion=QUERY_USES_URNS&facet=urn:li:adTargetingFacet:fieldsOfStudy&query=econ&locale.language=en&locale.country=US

Sample Response

{
    "elements": [
        {
            "urn": "urn:li:fieldOfStudy:100990",
            "facetUrn": "urn:li:adTargetingFacet:fieldsOfStudy",
            "name": "Economics"
        },
        {
            "urn": "urn:li:fieldOfStudy:101438",
            "facetUrn": "urn:li:adTargetingFacet:fieldsOfStudy",
            "name": "Business/Managerial Economics"
        },
        {
            "urn": "urn:li:fieldOfStudy:100994",
            "facetUrn": "urn:li:adTargetingFacet:fieldsOfStudy",
            "name": "International Economics"
        },
        {
            "urn": "urn:li:fieldOfStudy:100993",
            "facetUrn": "urn:li:adTargetingFacet:fieldsOfStudy",
            "name": "Development Economics and International Development"
        },
        {
            "urn": "urn:li:fieldOfStudy:100991",
            "facetUrn": "urn:li:adTargetingFacet:fieldsOfStudy",
            "name": "Applied Economics"
        },
    ..
    ]
}

Sample Request: GET Locations Entities for Location 'Africa'

GET https://api.linkedin.com/rest/adTargetingEntities?q=typeahead&queryVersion=QUERY_USES_URNS&facet=urn%3Ali%3AadTargetingFacet%3Alocations&query=afric&locale=(language:en,country:US)

GET https://api.linkedin.com/v2/adTargetingEntities?q=typeahead&queryVersion=QUERY_USES_URNS&facet=urn:li:adTargetingFacet:locations&query=afric&locale.language=en&locale.country=US

Sample Response

{
    "elements": [
       {
            "urn": "urn:li:geo:103537801",
            "facetUrn": "urn:li:adTargetingFacet:locations",
            "name": "Africa"
        },
        {
        
            "urn": "urn:li:geo:104035573",
            "facetUrn": "urn:li:adTargetingFacet:locations",
            "name": "South Africa"
        },
    ]
    
}

Find Entities by URNs

Get the metadata and value information for a collection of URNs.

Note

All requests are represented in protocol 2.0.0 and require the following header: X-Restli-Protocol-Version: 2.0.0

GET https://api.linkedin.com/rest/adTargetingEntities?q=urns&urns={URN}

GET https://api.linkedin.com/v2/adTargetingEntities?q=urns&urns={URN}

Parameters

Field Name Required Type Description
q Yes String This field should always be urns for this method.
urns Yes Array of URNs List of URNs requesting metadata for.
locale.language No String A lowercase two-letter language code as defined by ISO-639. Defaults to "en" if no value is provided.
locale.country No String An uppercase two-letter country code as defined by ISO-3166. Defaults to "US" if no value is provided.
queryVersion No String This field should always be QUERY_USES_URNS.
fetchType No String Determines how much of an URN's descendant tree is returned.
  • SINGLE_NODE: Default value. Resolve and return only the entities explicitly requested with no descendants.
  • LAZY: Resolve and return all entities except those with a large taxonomy size. Supported when passing a single URN value only.

Sample Request to Get Field of Study Names

GET https://api.linkedin.com/rest/adTargetingEntities?q=urns&urns=List(urn%3Ali%3AfieldOfStudy%3A100990,urn%3Ali%3Aorganization%3A1035,urn%3Ali%3Aseniority%3A9)&locale=(language:en,country:US)

GET https://api.linkedin.com/v2/adTargetingEntities?q=urns&urns=List(urn%3Ali%3AfieldOfStudy%3A100990,urn%3Ali%3Aorganization%3A1035,urn%3Ali%3Aseniority%3A9)&locale=(language:en,country:US)

Sample Response

{
    "elements": [
        {
            "facetUrn": "urn:li:adTargetingFacet:fieldsOfStudy",
            "name": "Economics",
            "urn": "urn:li:fieldOfStudy:100990"
        },
        {
            "facetUrn": "urn:li:adTargetingFacet:employersPast",
            "name": "Microsoft",
            "urn": "urn:li:organization:1035"
        },
        {
            "facetUrn": "urn:li:adTargetingFacet:seniorities",
            "name": "Partner",
            "urn": "urn:li:seniority:9"
        }
    ],
    "paging": {
        "count": 2147483647,
        "links": [],
        "start": 0
    }
}

Sample Request to Get Locations

GET https://api.linkedin.com/rest/adTargetingEntities?q=urns&queryVersion=QUERY_USES_URNS&urns=List(urn%3Ali%3Ageo%3A102095887,urn%3Ali%3Ageo%3A101857797)&locale=(language:en,country:US)

GET https://api.linkedin.com/v2/adTargetingEntities?q=urns&queryVersion=QUERY_USES_URNS&urns=List(urn%3Ali%3Ageo%3A102095887,urn%3Ali%3Ageo%3A101857797)&locale=(language:en,country:US)

Sample Response

{
  "elements": [
    {
      "urn": "urn:li:geo:102095887",
      "facetUrn": "urn:li:adTargetingFacet:locations",
      "name": "California, United States"
    },
    {
      "urn": "urn:li:geo:101857797",
      "facetUrn": "urn:li:adTargetingFacet:locations",
      "name": "Sacramento, California, United States"
    }
  ],
  "paging": {
    "count": 2147483647,
    "links": [],
    "start": 0
  }
}

Discovering Targeting Entities

Following table shows a list of all the targeting facets and the corresponding endpoint to retrieve list of entities for a given targeting facet.

Types of Finder

  • adTargetingFacet returns all the targeting entities for a given facet.
  • typeahead only returns targeting entities for a given targeting facet search query.
  • similarEntities returns similar targeting entities for a given targeting entity
AdTargetingFacets Supported Finder Recommended Finder
urn:li:adTargetingFacet:genders adTargetingFacet adTargetingFacet
urn:li:adTargetingFacet:industries adTargetingFacet, typeahead, similarEntities typeahead
urn:li:adTargetingFacet:jobFunctions adTargetingFacet adTargetingFacet
urn:li:adTargetingFacet:seniorities adTargetingFacet adTargetingFacet
urn:li:adTargetingFacet:ageRanges adTargetingFacet adTargetingFacet
urn:li:adTargetingFacet:locations typeahead only after Bing Geo Migration typeahead
urn:li:adTargetingFacet:profileLocations typeahead only after Bing Geo Migration typeahead
urn:li:adTargetingFacet:staffCountRanges adTargetingFacet adTargetingFacet
urn:li:adTargetingFacet:employers typeahead, similarEntities typeahead
urn:li:adTargetingFacet:employersPast typeahead, similarEntities typeahead
urn:li:adTargetingFacet:employersAll typeahead, similarEntities typeahead
urn:li:adTargetingFacet:groups typeahead, similarEntities typeahead
urn:li:adTargetingFacet:titles adTargetingFacet, typeahead, similarEntities typeahead
urn:li:adTargetingFacet:titlesPast adTargetingFacet, typeahead, similarEntities typeahead
urn:li:adTargetingFacet:titlesAll adTargetingFacet, typeahead, similarEntities typeahead
urn:li:adTargetingFacet:skills adTargetingFacet, typeahead, similarEntities typeahead
urn:li:adTargetingFacet:schools typeahead typeahead
urn:li:adTargetingFacet:interfaceLocales adTargetingFacet adTargetingFacet
urn:li:adTargetingFacet:followedCompanies typeahead, similarEntities typeahead
urn:li:adTargetingFacet:degrees adTargetingFacet, typeahead typeahead
urn:li:adTargetingFacet:fieldsOfStudy adTargetingFacet, typeahead typeahead
urn:li:adTargetingFacet:yearsOfExperienceRanges adTargetingFacet adTargetingFacet
urn:li:adTargetingFacet:firstDegreeConnectionCompanies typeahead, similarEntities typeahead
urn:li:adTargetingFacet:audienceMatchingSegments N/A N/A
urn:li:adTargetingFacet:dynamicSegments N/A N/A
urn:li:adTargetingFacet:interests adTargetingFacet, typeahead typeahead
urn:li:adTargetingFacet:memberBehaviors adTargetingFacet, typeahead adTargetingFacet
urn:li:adTargetingFacet:companyCategory adTargetingFacet, typeahead adTargetingFacet
urn:li:adTargetingFacet:growthRate adTargetingFacet, typeahead adTargetingFacet
urn:li:adTargetingFacet:revenue adTargetingFacet, typeahead adTargetingFacet

Note

LinkedIn is migrating to a new geo data source (i.e. Bing geo). To understand the complete migration plan for Bing geo, see Bing geo Migration Guide.