openapi: 3.0.0
info:
  title: LinkedIn People API
  description: |
    Search LinkedIn members by first name, last name or both.

    Each member comes with a name, a profile link and a location, plus the headline, company, school and photo when LinkedIn shows them. LinkedIn shows at most 50 members for a name, and the response also gives the total number of members with that name.
  version: 1.0.0
servers:
  - url: https://www.searchapi.io/api/v1
paths:
  /search:
    get:
      summary: LinkedIn People Search
      security:
        - ApiKeyAuth: []
        - ApiKeyQuery: []
      parameters:
        - name: engine
          in: query
          required: true
          description: 'Search engine. Must be set to: `linkedin_people`'
          schema:
            type: string
            enum: ["linkedin_people"]
        - name: first_name
          in: query
          required: false
          description: First name to search for, such as `John`. It must contain a letter or a digit. At least one of `first_name` and `last_name` is required.
          schema:
            type: string
            maxLength: 255
            pattern: '^[^%{}]*$'
        - name: last_name
          in: query
          required: false
          description: Last name to search for, such as `Smith`. It must contain a letter or a digit. At least one of `first_name` and `last_name` is required.
          schema:
            type: string
            maxLength: 255
            pattern: '^[^%{}]*$'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication Error. The API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server Error. Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Timeout. We could not retrieve results in 90 seconds.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"'
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key
      description: Pass API key as query parameter
  schemas:
    SearchResponse:
      type: object
      properties:
        search_metadata:
          $ref: '#/components/schemas/SearchMetadata'
        search_parameters:
          $ref: '#/components/schemas/SearchParameters'
        search_information:
          $ref: '#/components/schemas/SearchInformation'
        profiles:
          type: array
          items:
            $ref: '#/components/schemas/Profile'
          description: "Members with the name, in LinkedIn's order, up to 50"
        error:
          type: string
          description: "Error message, such as for a name no member has"
    SearchMetadata:
      type: object
      required: [status, created_at]
      properties:
        id:
          type: string
          description: "Unique identifier for the search request"
        status:
          type: string
          description: "Status of the search request"
        created_at:
          type: string
          format: date-time
          description: "Timestamp when the search was created"
        request_time_taken:
          type: number
          description: "Time taken to make the request in seconds"
        parsing_time_taken:
          type: number
          description: "Time taken to parse the results in seconds"
        total_time_taken:
          type: number
          description: "Total time taken for the search in seconds"
        request_url:
          type: string
          description: "LinkedIn URL for this search"
        html_url:
          type: string
          description: "URL to view HTML results"
        json_url:
          type: string
          description: "URL to view JSON results"
    SearchParameters:
      type: object
      properties:
        engine:
          type: string
          description: "Search engine used"
        first_name:
          type: string
          description: "First name searched"
        last_name:
          type: string
          description: "Last name searched"
    SearchInformation:
      type: object
      required: [total_results]
      properties:
        total_results:
          type: integer
          description: "Number of members LinkedIn shows for the name, rounded down for large counts"
        is_total_results_approximate:
          type: boolean
          description: "Whether LinkedIn rounds the total and shows a plus sign, as in 104000+"
    Profile:
      type: object
      required: [position, username, link]
      properties:
        position:
          type: integer
          description: "Position of the member in LinkedIn's results"
        name:
          type: string
          description: "Member's name as LinkedIn shows it"
        username:
          type: string
          description: "Member's profile handle, the part of the profile link after /in/"
        link:
          type: string
          description: "LinkedIn profile page of the member"
        headline:
          type: string
          description: "Member's LinkedIn headline"
        location:
          type: string
          description: "Member's location as LinkedIn shows it"
        company_name:
          type: string
          description: "First company LinkedIn lists in the member's experience"
        school_name:
          type: string
          description: "First school LinkedIn lists in the member's education"
        thumbnail:
          type: string
          description: "Member's profile photo"
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Error message describing what went wrong