LinkedIn Ad Targeting Entities API

openapi: 3.1.0
info:
  title: LinkedIn Compliance Events Access Control Ad Targeting Entities API
  description: LinkedIn provides Compliance API Guides for monitoring, archiving, and management of communications for enterprises in regulated industries. The Compliance Events API allows applications to archive all LinkedIn activities from the past 30 days of a regulated, authenticated member.
  version: 1.0.0
  contact:
    name: LinkedIn API Support
    url: https://docs.microsoft.com/en-us/linkedin/compliance/
servers:
- url: https://api.linkedin.com
  description: LinkedIn Production API Server
security:
- OAuth2Auth:
  - r_compliance
tags:
- name: Ad Targeting Entities
  description: APIs to discover and retrieve ad targeting facets and entities
paths:
  /adTargetingFacets:
    get:
      tags:
      - Ad Targeting Entities
      summary: LinkedIn Get List of Available Ad Targeting Facets
      description: Retrieve the list of available ad targeting facets. Facets are high-level categories of targeting types available for ad campaigns.
      operationId: getAdTargetingFacets
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: ''
      parameters:
      - name: LinkedIn-Version
        in: header
        required: true
        schema:
          type: string
        description: LinkedIn API version
        example: '202401'
      - name: X-Restli-Protocol-Version
        in: header
        required: true
        schema:
          type: string
        description: RestLi protocol version
        example: 2.0.0
      responses:
        '200':
          description: Successfully retrieved ad targeting facets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdTargetingFacetsResponse'
              examples:
                SuccessResponse:
                  $ref: '#/components/examples/AdTargetingFacetsResponseExample'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /adTargetingEntities:
    get:
      tags:
      - Ad Targeting Entities
      summary: LinkedIn Get Ad Targeting Entities Using Typeahead Search
      description: Search for ad targeting entities within a facet using typeahead search. Returns entities matching the search query.
      operationId: searchAdTargetingEntities
      x-microcks-operation:
        dispatcher: FALLBACK
        dispatcherRules: ''
      parameters:
      - name: LinkedIn-Version
        in: header
        required: true
        schema:
          type: string
        description: LinkedIn API version
        example: '202401'
      - name: X-Restli-Protocol-Version
        in: header
        required: true
        schema:
          type: string
        description: RestLi protocol version
        example: 2.0.0
      - name: q
        in: query
        required: true
        schema:
          type: string
          enum:
          - typeahead
        description: Query type
        example: typeahead
      - name: query
        in: query
        required: true
        schema:
          type: string
        description: Search query string (URL encoded)
        example: united%20states
      - name: facet
        in: query
        required: true
        schema:
          type: string
        description: Facet URN to search within (URL encoded)
        example: urn%3Ali%3AadTargetingFacet%3Alocations
      - name: queryVersion
        in: query
        required: false
        schema:
          type: string
          enum:
          - QUERY_USES_URNS
        description: Query version format
        example: QUERY_USES_URNS
      - name: start
        in: query
        required: false
        schema:
          type: integer
          default: 0
        description: Starting index for pagination
        example: 0
      - name: count
        in: query
        required: false
        schema:
          type: integer
          default: 10
          maximum: 100
        description: Number of results to return
        example: 10
      responses:
        '200':
          description: Successfully retrieved ad targeting entities
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdTargetingEntitiesResponse'
              examples:
                SuccessResponse:
                  $ref: '#/components/examples/AdTargetingEntitiesResponseExample'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    Paging:
      type: object
      properties:
        start:
          type: integer
          description: Starting index
          example: 0
        count:
          type: integer
          description: Number of results returned
          example: 10
        total:
          type: integer
          description: Total number of results
          example: 100
        links:
          type: array
          items:
            $ref: '#/components/schemas/PagingLink'
    PagingLink:
      type: object
      properties:
        rel:
          type: string
          example: next
        href:
          type: string
          example: /rest/adTargetingEntities?q=typeahead&query=united%20states&start=10&count=10
        type:
          type: string
          example: application/json
    AdTargetingFacet:
      type: object
      properties:
        facetName:
          type: string
          description: Name of the targeting facet
          example: jobFunctions
        urn:
          type: string
          description: URN identifier for the facet
          example: urn:li:adTargetingFacet:jobFunctions
        entityTypes:
          type: array
          items:
            type: string
          description: Types of entities in this facet
          example:
          - FUNCTION
        availableEntityFinders:
          type: array
          items:
            type: string
            enum:
            - AD_TARGETING_FACET
            - TYPEAHEAD
            - SIMILAR_ENTITIES
          description: Available methods to find entities
          example:
          - AD_TARGETING_FACET
      required:
      - facetName
      - urn
      - entityTypes
    AdTargetingEntitiesResponse:
      type: object
      properties:
        elements:
          type: array
          items:
            $ref: '#/components/schemas/AdTargetingEntity'
        paging:
          $ref: '#/components/schemas/Paging'
    AdTargetingEntity:
      type: object
      properties:
        name:
          type: string
          description: Display name of the entity
          example: United States
        urn:
          type: string
          description: URN identifier for the entity
          example: urn:li:geo:103644278
        facetUrn:
          type: string
          description: URN of the parent facet
          example: urn:li:adTargetingFacet:locations
      required:
      - name
      - urn
      - facetUrn
    ErrorResponse:
      type: object
      properties:
        status:
          type: integer
          description: HTTP status code
          example: 400
        message:
          type: string
          description: Error message
          example: Invalid request parameters
        code:
          type: string
          description: Error code
          example: INVALID_PARAMS
    AdTargetingFacetsResponse:
      type: object
      properties:
        elements:
          type: array
          items:
            $ref: '#/components/schemas/AdTargetingFacet'
        paging:
          $ref: '#/components/schemas/Paging'
  examples:
    AdTargetingEntitiesResponseExample:
      summary: Location targeting entities
      value:
        paging:
          start: 0
          count: 10
          links:
          - type: application/json
            rel: next
            href: /rest/adTargetingEntities?q=typeahead&query=united%20states&start=10&count=10&facet=urn%3Ali%3AadTargetingFacet%3Alocations&queryVersion=QUERY_USES_URNS
        elements:
        - name: United States
          urn: urn:li:geo:103644278
          facetUrn: urn:li:adTargetingFacet:locations
        - name: California, United States
          urn: urn:li:geo:102095887
          facetUrn: urn:li:adTargetingFacet:locations
        - name: Texas, United States
          urn: urn:li:geo:102748797
          facetUrn: urn:li:adTargetingFacet:locations
        - name: New York, United States
          urn: urn:li:geo:105080838
          facetUrn: urn:li:adTargetingFacet:locations
        - name: Florida, United States
          urn: urn:li:geo:101318387
          facetUrn: urn:li:adTargetingFacet:locations
        - name: Los Angeles County, California, United States
          urn: urn:li:geo:103104382
          facetUrn: urn:li:adTargetingFacet:locations
        - name: New York, New York, United States
          urn: urn:li:geo:102571732
          facetUrn: urn:li:adTargetingFacet:locations
        - name: Illinois, United States
          urn: urn:li:geo:101949407
          facetUrn: urn:li:adTargetingFacet:locations
        - name: Pennsylvania, United States
          urn: urn:li:geo:102986501
          facetUrn: urn:li:adTargetingFacet:locations
        - name: Georgia, United States
          urn: urn:li:geo:103950076
          facetUrn: urn:li:adTargetingFacet:locations
    AdTargetingFacetsResponseExample:
      summary: List of ad targeting facets
      value:
        paging:
          start: 0
          count: 10
          links: []
        elements:
        - entityTypes:
          - FUNCTION
          facetName: jobFunctions
          urn: urn:li:adTargetingFacet:jobFunctions
          availableEntityFinders:
          - AD_TARGETING_FACET
        - entityTypes:
          - AGE
          facetName: ageRanges
          urn: urn:li:adTargetingFacet:ageRanges
          availableEntityFinders:
          - AD_TARGETING_FACET
        - entityTypes:
          - GROUP
          facetName: groups
          urn: urn:li:adTargetingFacet:groups
          availableEntityFinders:
          - TYPEAHEAD
          - SIMILAR_ENTITIES
        - entityTypes:
          - COMPANY
          facetName: employers
          urn: urn:li:adTargetingFacet:employers
          availableEntityFinders:
          - TYPEAHEAD
          - SIMILAR_ENTITIES
        - entityTypes:
          - INDUSTRY
          facetName: industries
          urn: urn:li:adTargetingFacet:industries
          availableEntityFinders:
          - AD_TARGETING_FACET
          - TYPEAHEAD
          - SIMILAR_ENTITIES
        - entityTypes:
          - SENIORITY
          facetName: seniorities
          urn: urn:li:adTargetingFacet:seniorities
          availableEntityFinders:
          - AD_TARGETING_FACET
        - entityTypes:
          - COUNTRY_GROUP
          - COUNTRY
          - STATE
          - REGION
          facetName: locations
          urn: urn:li:adTargetingFacet:locations
          availableEntityFinders:
          - AD_TARGETING_FACET
          - TYPEAHEAD
        - entityTypes:
          - INTEREST
          facetName: interests
          urn: urn:li:adTargetingFacet:interests
          availableEntityFinders:
          - TYPEAHEAD
          - AD_TARGETING_FACET
  securitySchemes:
    OAuth2Auth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.linkedin.com/oauth/v2/authorization
          tokenUrl: https://www.linkedin.com/oauth/v2/accessToken
          scopes:
            r_compliance: Read compliance data