Ad Targeting
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.
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:
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"
}
]
}
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.
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
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
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
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.
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:
|
| 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.
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.
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:
|
| 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'
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'
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
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.
|
Sample Request to Get Field of Study Names
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
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.
Note
As part of our ongoing efforts to provide a safe and trusted platform for members, we have decided to disable Member Groups’ targeting within the European Economic Area (EEA) and Switzerland (CH) starting May 2024. This means you can no longer use the urn:li:adTargetingFacet:groups facet to target members based on their group membership within these regions.