openapi: 3.0.3
info:
  title: People Data Labs API
  description: >-
    People Data Labs (PDL) provides APIs for enriching and building people and
    company profiles at scale. The API offers person enrichment, person search,
    person identification, company enrichment, company search, IP enrichment,
    and job posting search across a dataset of professional profiles and
    organizations.
  version: v5
  contact:
    name: People Data Labs Support
    url: https://docs.peopledatalabs.com/docs/support
  license:
    name: People Data Labs Terms of Service
    url: https://www.peopledatalabs.com/terms-of-service
servers:
  - url: https://api.peopledatalabs.com/v5
    description: People Data Labs production API
security:
  - ApiKeyAuth: []
tags:
  - name: Person
    description: Person enrichment, search, and identification operations.
  - name: Company
    description: Company enrichment and search operations.
  - name: IP
    description: IP-based enrichment operations.
  - name: Jobs
    description: Job posting search operations.
  - name: Autocomplete
    description: Autocomplete suggestions for fields like skills and titles.
paths:
  /person/enrich:
    get:
      tags:
        - Person
      summary: Enrich a person profile
      description: >-
        Returns a single enriched person profile based on identifiers such as
        email, phone, profile URL, name, or company.
      parameters:
        - name: email
          in: query
          schema:
            type: string
        - name: phone
          in: query
          schema:
            type: string
        - name: profile
          in: query
          schema:
            type: string
        - name: first_name
          in: query
          schema:
            type: string
        - name: last_name
          in: query
          schema:
            type: string
        - name: company
          in: query
          schema:
            type: string
        - name: min_likelihood
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 10
      responses:
        '200':
          description: A single enriched person record.
  /person/search:
    get:
      tags:
        - Person
      summary: Search for person profiles
      description: >-
        Returns multiple person profiles matching an SQL or Elasticsearch query.
      parameters:
        - name: sql
          in: query
          schema:
            type: string
        - name: query
          in: query
          schema:
            type: string
        - name: size
          in: query
          schema:
            type: integer
            default: 1
            maximum: 100
        - name: from
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A list of matching person profiles.
  /person/identify:
    get:
      tags:
        - Person
      summary: Identify a person
      description: >-
        Returns a list of likely matching person profiles for the supplied
        identifiers, with match likelihood scores.
      parameters:
        - name: email
          in: query
          schema:
            type: string
        - name: phone
          in: query
          schema:
            type: string
        - name: first_name
          in: query
          schema:
            type: string
        - name: last_name
          in: query
          schema:
            type: string
      responses:
        '200':
          description: A list of likely matching person profiles.
  /person/bulk:
    post:
      tags:
        - Person
      summary: Bulk person enrichment
      description: Enrich multiple person profiles in a single request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                requests:
                  type: array
                  items:
                    type: object
      responses:
        '200':
          description: An array of enriched person records.
  /company/enrich:
    get:
      tags:
        - Company
      summary: Enrich a company profile
      description: Returns an enriched company profile based on identifiers such as website, name, or LinkedIn profile.
      parameters:
        - name: name
          in: query
          schema:
            type: string
        - name: website
          in: query
          schema:
            type: string
        - name: profile
          in: query
          schema:
            type: string
        - name: ticker
          in: query
          schema:
            type: string
        - name: location
          in: query
          schema:
            type: string
      responses:
        '200':
          description: An enriched company record.
  /company/search:
    get:
      tags:
        - Company
      summary: Search for companies
      description: Returns multiple company profiles matching an SQL or Elasticsearch query.
      parameters:
        - name: sql
          in: query
          schema:
            type: string
        - name: query
          in: query
          schema:
            type: string
        - name: size
          in: query
          schema:
            type: integer
            default: 1
            maximum: 100
      responses:
        '200':
          description: A list of matching company profiles.
  /ip/enrich:
    get:
      tags:
        - IP
      summary: IP enrichment
      description: Returns company and location data for the supplied IP address.
      parameters:
        - name: ip
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An enriched IP record.
  /job_posting/search:
    get:
      tags:
        - Jobs
      summary: Search job postings
      description: Returns job postings matching the supplied query.
      parameters:
        - name: sql
          in: query
          schema:
            type: string
        - name: query
          in: query
          schema:
            type: string
        - name: size
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A list of matching job postings.
  /autocomplete:
    get:
      tags:
        - Autocomplete
      summary: Autocomplete suggestions
      description: Returns autocomplete suggestions for fields like skill, title, company, and location.
      parameters:
        - name: field
          in: query
          required: true
          schema:
            type: string
            enum:
              - skill
              - title
              - company
              - school
              - location
              - country
              - region
              - role
              - sub_role
              - industry
        - name: text
          in: query
          schema:
            type: string
        - name: size
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A list of autocomplete suggestions.
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key