openapi: 3.1.0
info:
  title: LinkedIn Marketing Audience Insights API
  description: >-
    Audience Insights API enables you to discover and identify audience segments
    that meet your target persona, demonstrate interest and engagement in relevant
    products/offerings, uncover insights about companies the target audience works for,
    and activate audience for targeting in sponsored ad campaigns on LinkedIn.

    Note: This is a private API available to qualified developers who meet additional
    criteria for access.
  version: 1.0.0
  contact:
    name: LinkedIn Marketing API Support
    url: https://learn.microsoft.com/en-us/linkedin/marketing/
servers:
- url: https://api.linkedin.com/rest
  description: LinkedIn REST API Server
components:
  securitySchemes:
    OAuth2Auth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://www.linkedin.com/oauth/v2/authorization
          tokenUrl: https://www.linkedin.com/oauth/v2/accessToken
          scopes:
            r_ads: Read advertising data
  schemas:
    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
    AdTargetingFacetsResponse:
      type: object
      properties:
        elements:
          type: array
          items:
            $ref: '#/components/schemas/AdTargetingFacet'
        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
    AdTargetingEntitiesResponse:
      type: object
      properties:
        elements:
          type: array
          items:
            $ref: '#/components/schemas/AdTargetingEntity'
        paging:
          $ref: '#/components/schemas/Paging'
    AudienceInsightsRequest:
      type: object
      properties:
        request:
          type: object
          properties:
            requestMetaData:
              $ref: '#/components/schemas/RequestMetaData'
            targetingCriteria:
              $ref: '#/components/schemas/TargetingCriteria'
            groupBy:
              type: string
              description: Facet URN to group insights by
              example: "urn:li:adTargetingFacet:interests"
          required:
          - targetingCriteria
          - groupBy
    RequestMetaData:
      type: object
      properties:
        sponsoredAccount:
          type: string
          description: URN of the sponsored account
          example: "urn:li:sponsoredAccount:123456789"
    TargetingCriteria:
      type: object
      properties:
        include:
          type: object
          properties:
            and:
              type: array
              items:
                type: object
                properties:
                  or:
                    type: object
                    additionalProperties:
                      type: array
                      items:
                        type: string
    AudienceInsightsResponse:
      type: object
      properties:
        value:
          type: object
          properties:
            audienceInsight:
              $ref: '#/components/schemas/AudienceInsight'
            totalAudienceCount:
              type: integer
              description: Total count of the target audience
              example: 5500000
    AudienceInsight:
      type: object
      properties:
        segmentations:
          type: array
          items:
            $ref: '#/components/schemas/InsightSegmentation'
        groupedBy:
          type: string
          description: Facet URN the insights are grouped by
          example: "urn:li:adTargetingFacet:interests"
    InsightSegmentation:
      type: object
      properties:
        entityCount:
          type: integer
          description: Number of members matching this segment
          example: 4900000
        entityPercentage:
          type: integer
          description: Percentage of audience matching this segment
          example: 89
        value:
          type: string
          description: URN of the segment value
          example: "urn:li:interest:71363"
    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"
    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"
  examples:
    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"
    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"
    AudienceInsightsRequestExample:
      summary: Request for interests of Finance directors in US
      value:
        request:
          requestMetaData:
            sponsoredAccount: "urn:li:sponsoredAccount:123456789"
          targetingCriteria:
            include:
              and:
              - or:
                  "urn:li:adTargetingFacet:locations":
                  - "urn:li:geo:103644278"
              - or:
                  "urn:li:adTargetingFacet:interfaceLocales":
                  - "urn:li:locale:en_US"
              - or:
                  "urn:li:adTargetingFacet:jobFunctions":
                  - "urn:li:function:10"
          groupBy: "urn:li:adTargetingFacet:interests"
    AudienceInsightsResponseExample:
      summary: Audience insights response with top interests
      value:
        value:
          audienceInsight:
            segmentations:
            - entityCount: 4900000
              entityPercentage: 89
              value: "urn:li:interest:71363"
            - entityCount: 4500000
              entityPercentage: 82
              value: "urn:li:interest:420"
            - entityCount: 4500000
              entityPercentage: 82
              value: "urn:li:interest:2689786"
            - entityCount: 4400000
              entityPercentage: 80
              value: "urn:li:interest:3440"
            - entityCount: 4300000
              entityPercentage: 78
              value: "urn:li:interest:1537154"
            groupedBy: "urn:li:adTargetingFacet:interests"
          totalAudienceCount: 5500000
security:
- OAuth2Auth:
  - r_ads
tags:
- name: Ad Targeting Entities
  description: APIs to discover and retrieve ad targeting facets and entities
- name: Audience Insights
  description: APIs to fetch audience insights based on targeting criteria
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'
  /targetingAudienceInsights:
    post:
      tags:
      - Audience Insights
      summary: LinkedIn Fetch Audience Insights by Targeting Criteria
      description: >-
        Retrieve aggregated demographic insights, firmographic details, locations,
        and interests/behaviors for a target audience based on specified targeting criteria.
      operationId: getAudienceInsights
      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: action
        in: query
        required: true
        schema:
          type: string
          enum:
          - audienceInsights
        description: Action to perform
        example: "audienceInsights"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AudienceInsightsRequest'
            examples:
              FinanceDirectorsInUS:
                $ref: '#/components/examples/AudienceInsightsRequestExample'
      responses:
        '200':
          description: Successfully retrieved audience insights
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudienceInsightsResponse'
              examples:
                SuccessResponse:
                  $ref: '#/components/examples/AudienceInsightsResponseExample'
        '400':
          description: Bad request - invalid targeting criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden - insufficient permissions for Audience Insights API
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'