People Data Labs Person Endpoints API

openapi: 3.2.0
info:
  description: People Data Labs API
  title: api.peopledatalabs.com Autocomplete Person Endpoints API
  version: '5.0'
servers:
- url: https://api.peopledatalabs.com
tags:
- name: Person Endpoints
paths:
  /v5/person/enrich:
    get:
      security:
      - APIKeyHeader: []
      parameters:
      - name: Content-Type
        in: header
        description: The content type
        schema:
          type: string
          default: application/json
          enum:
          - application/json
      - name: pdl_id
        in: query
        description: The PDL ID of the person to enrich
        schema:
          type: string
          example: qEnOZ5Oh0poWnQ1luFBfVw_0000
      - name: name
        in: query
        description: The person's full name, at least first and last
        schema:
          type: string
          example: Jennifer C. Jackson
      - name: first_name
        in: query
        description: The person's first name
        schema:
          type: string
          example: Jennifer
      - name: last_name
        in: query
        description: The person's last name
        schema:
          type: string
          example: Jackson
      - name: middle_name
        in: query
        description: The person's middle name
        schema:
          type: string
          example: Cassandra
      - name: location
        in: query
        description: A location in which a person lives
        schema:
          type: string
          example: Medford, OR USA
      - name: street_address
        in: query
        description: A street address in which the person lives
        schema:
          type: string
          example: 1234 Main Street
      - name: locality
        in: query
        description: A locality in which the person lives
        schema:
          type: string
          example: Boise
      - name: region
        in: query
        description: A state or region in which the person lives
        schema:
          type: string
          example: Idaho
      - name: country
        in: query
        description: A country in which the person lives
        schema:
          type: string
          example: United States
      - name: postal_code
        in: query
        description: The postal code where the person lives. If there is no value for country, the postal code is assumed to be US
        schema:
          type: string
          example: '83701'
      - name: company
        in: query
        description: A name, website, or social url of a company where the person has worked
        schema:
          type: string
          example: Amazon
      - name: school
        in: query
        description: A name, website, or social url of a university or college the person has attended
        schema:
          type: string
          example: University of Iowa
      - name: phone
        in: query
        description: A phone number the person has used
        schema:
          type: string
          example: +1 555-234-1234
      - name: email
        in: query
        description: An email the person has used
        schema:
          type: string
          example: renee.c.paulsen1959@yahoo.com
      - name: email_hash
        in: query
        description: A SHA-256 or MD5 email hash
        schema:
          type: string
          example: e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4
      - name: profile
        in: query
        description: A social profile the person has used. https://docs.peopledatalabs.com/docs/social-networks
        schema:
          type: string
          example: https://linkedin.com/in/seanthorne
      - name: lid
        in: query
        description: The person's LinkedIn ID
        schema:
          type: string
          example: '145991517'
      - name: birth_date
        in: query
        description: 'The person''s birth date: either the year or a full birth date in the format YYYY-MM-DD'
        schema:
          type: string
          example: '1996-10-01'
      - name: data_include
        in: query
        description: A comma-separated string of fields that you would like the response to include. Begin the string with a - if you would instead like to exclude the specified fields. If you would like to exclude all data from being returned, use data_include=""
        schema:
          type: string
          example: full_name,emails.address
      - name: pretty
        in: query
        description: Whether the output should have human-readable indentation
        schema:
          type: boolean
          default: false
      - name: min_likelihood
        in: query
        description: The minimum likelihood score that a response must have in order to count as a match
        schema:
          type: integer
          maximum: 10
          minimum: 0
          format: int32
          default: 2
      - name: include_if_matched
        in: query
        description: If set to true, includes a top-level (alongside "data", "status", etc) field "matched" which includes a value for each queried field parameter that was "matched-on" during our internal query.
        schema:
          type: boolean
          default: false
      - name: required
        in: query
        description: The fields a response must have in order to count as a match
        schema:
          type: string
          example: education AND (emails OR phone_numbers)
      - name: titlecase
        in: query
        description: Setting titlecase to true will titlecase the person data in 200 responses.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Person Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '400':
          description: Request contained either missing or invalid parameters
        '401':
          description: Request contained a missing or invalid key
        '402':
          description: You have reached your account maximum (all matches used)
        '404':
          description: No records were found matching your request
        '405':
          description: Request method is not allowed on the requested resource
        '429':
          description: An error occurred due to requests hitting the API too quickly
      summary: /person/enrich
      tags:
      - Person Endpoints
  /v5/person/identify:
    get:
      security:
      - APIKeyHeader: []
      parameters:
      - name: Content-Type
        in: header
        description: The content type
        schema:
          type: string
          default: application/json
          enum:
          - application/json
      - name: name
        in: query
        description: The person's full name, at least first and last
        schema:
          type: string
          example: Jennifer C. Jackson
      - name: first_name
        in: query
        description: The person's first name
        schema:
          type: string
          example: Jennifer
      - name: last_name
        in: query
        description: The person's last name
        schema:
          type: string
          example: Jackson
      - name: middle_name
        in: query
        description: The person's middle name
        schema:
          type: string
          example: Cassandra
      - name: location
        in: query
        description: A location in which a person lives
        schema:
          type: string
          example: Medford, OR USA
      - name: street_address
        in: query
        description: A street address in which the person lives
        schema:
          type: string
          example: 1234 Main Street
      - name: locality
        in: query
        description: A locality in which the person lives
        schema:
          type: string
          example: Boise
      - name: region
        in: query
        description: A state or region in which the person lives
        schema:
          type: string
          example: Idaho
      - name: country
        in: query
        description: A country in which the person lives
        schema:
          type: string
          example: United States
      - name: postal_code
        in: query
        description: The postal code where the person lives. If there is no value for country, the postal code is assumed to be US
        schema:
          type: string
          example: '83701'
      - name: company
        in: query
        description: A name, website, or social url of a company where the person has worked
        schema:
          type: string
          example: Amazon
      - name: school
        in: query
        description: A name, website, or social url of a university or college the person has attended
        schema:
          type: string
          example: University of Iowa
      - name: phone
        in: query
        description: A phone number the person has used
        schema:
          type: string
          example: +1 555-234-1234
      - name: email
        in: query
        description: An email the person has used
        schema:
          type: string
          example: renee.c.paulsen1959@yahoo.com
      - name: email_hash
        in: query
        description: A sha256 email hash
        schema:
          type: string
          example: e206e6cd7fa5f9499fd6d2d943dcf7d9c1469bad351061483f5ce7181663b8d4
      - name: profile
        in: query
        description: A social profile the person has used. https://docs.peopledatalabs.com/docs/social-networks
        schema:
          type: string
          example: https://linkedin.com/in/seanthorne
      - name: lid
        in: query
        description: The person's LinkedIn ID
        schema:
          type: string
          example: '145991517'
      - name: birth_date
        in: query
        description: 'The person''s birth date: either the year or a full birth date in the format YYYY-MM-DD'
        schema:
          type: string
          example: '1996-10-01'
      - name: pretty
        in: query
        description: Whether the output should have human-readable indentation
        schema:
          type: boolean
          default: false
      - name: titlecase
        in: query
        description: Setting titlecase to true will titlecase the person data in 200 responses.
        schema:
          type: boolean
          default: false
      - name: data_include
        in: query
        description: A comma-separated string of fields that you would like the response to include. Begin the string with a - if you would instead like to exclude the specified fields. If you would like to exclude all data from being returned, use data_include=""
        schema:
          type: string
          example: full_name,emails.address
      - name: include_if_matched
        in: query
        description: If true, the response will include the field matches.matched_on that contains a list of every query input that matched this profile
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Profiles Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '400':
          description: Request contained either missing or invalid parameters
        '401':
          description: Request contained either missing or invalid key
        '402':
          description: You have reached your account maximum (all matches used)
        '404':
          description: No records were found matching your request
        '405':
          description: Request method is not allowed on the requested resource
        '429':
          description: An error occurred due to requests hitting the API too quickly
      summary: /person/identify
      tags:
      - Person Endpoints
  /v5/person/search:
    get:
      security:
      - APIKeyHeader: []
      parameters:
      - name: Content-Type
        in: header
        description: The content type
        schema:
          type: string
          default: application/json
          enum:
          - application/json
      - name: query
        in: query
        description: An Elasticsearch (v7.7) query. See our underlying Elasticsearch mapping for reference. You can build a query using the Query Builder Tool (https://dashboard.peopledatalabs.com/tools/query-builder)
        schema:
          type: string
          example: '{"query": {"term": {"job_company_name": "people data labs"}}}'
      - name: sql
        in: query
        description: 'A SQL query of the format: SELECT * FROM person WHERE XXX, where XXX is a standard SQL boolean query involving our person fields'
        schema:
          type: string
          example: SELECT * FROM person WHERE job_company_name='people data labs'
      - name: size
        in: query
        description: The number of matched records to return for this query if they exist*. Must be between 1 and 100
        schema:
          type: integer
          maximum: 100
          minimum: 1
          format: int32
          default: 1
      - name: scroll_token
        in: query
        description: An offset key for paginating between batches. Can be used for any number of records. Each search API response returns a scroll_token which can be used to fetch the next size records.
        schema:
          type: string
          example: 104$14.278746
      - name: dataset
        in: query
        description: The dataset category to return records from. Can be multiple comma seperated categories or all
        schema:
          type: string
          default: resume
      - name: titlecase
        in: query
        description: Setting titlecase to true will titlecase any records returned
        schema:
          type: boolean
          default: false
      - name: data_include
        in: query
        description: A comma-separated string of fields that you would like the response to include. Begin the string with a - if you would instead like to exclude the specified fields. If you would like to exclude all data from being returned, use data_include=""
        schema:
          type: string
          example: full_name,emails.address
      - name: pretty
        in: query
        description: Whether the output should have human-readable indentation.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Person Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '400':
          description: Request contained either missing or invalid parameters
        '401':
          description: Request contained a missing or invalid key
        '402':
          description: You have reached your account maximum (all matches used)
        '404':
          description: Request didn't return any records.
        '405':
          description: Request method is not allowed on the requested resource
        '429':
          description: An error occurred due to requests hitting the API too quickly
      summary: /person/search
      tags:
      - Person Endpoints
    post:
      security:
      - APIKeyHeader: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  description: An Elasticsearch (v7.7) query. See our underlying Elasticsearch mapping for reference.
                  example: '{"query": {"term": {"industry": "computer software"}}}'
                sql:
                  type: string
                  description: 'A SQL query of the format: SELECT * FROM person WHERE XXX, where XXX is a standard SQL boolean query involving our person fields'
                  example: SELECT * FROM person WHERE industry ='computer software'
                size:
                  type: integer
                  description: The number of matched records to return for this query if they exist*. Must be between 1 and 100
                  maximum: 100
                  minimum: 1
                  format: int32
                  default: 1
                from:
                  type: integer
                  description: An offset value for pagination. Can be a number between 0 and 9999. Pagination can be executed up to a maximum of 10,000 records per query. Be sure to use the "total" response field to help discover how many total records exist in the dataset for your query
                  maximum: 9999
                  minimum: 0
                  format: int32
                  default: 0
                scroll_token:
                  type: string
                  description: Each search API response returns a scroll_token. Include it in the next request to fetch the next size matching records
                  example: 104$14.278746
                dataset:
                  type: string
                  description: Specifies which dataset(s) the API should search against
                  default: resume
                  example: all
                titlecase:
                  type: boolean
                  description: Setting titlecase to true will titlecase any records returned
                  default: false
                data_include:
                  type: string
                  description: A comma-separated string of fields that you would like the response to include. Begin the string with a - if you would instead like to exclude the specified fields. If you would like to exclude all data from being returned, use data_include=""
                  example: full_name,emails.address
                pretty:
                  type: boolean
                  description: Whether the output should have human-readable indentation.
                  default: false
              oneOf:
              - required:
                - query
              - required:
                - sql
      responses:
        '200':
          description: Person Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Person'
        '400':
          description: Request contained either missing or invalid parameters
        '401':
          description: Request contained a missing or invalid key
        '402':
          description: You have reached your account maximum (all matches used)
        '404':
          description: Request didn't return any records.
        '405':
          description: Request method is not allowed on the requested resource
        '429':
          description: An error occurred due to requests hitting the API too quickly
      summary: /person/search
      tags:
      - Person Endpoints
  /v5/person/retrieve/{person_id}:
    get:
      security:
      - APIKeyHeader: []
      parameters:
      - name: Content-Type
        in: header
        description: The content type
        schema:
          type: string
          default: application/json
          enum:
          - application/json
      - name: person_id
        in: path
        description: The ID of a person
        schema:
          type: string
        required: true
      - name: titlecase
        in: query
        description: Setting titlecase to true will titlecase the person data in 200 responses.
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Person Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonRetrieve'
        '400':
          description: Request contained either missing or invalid parameters
        '401':
          description: Request contained a missing or invalid key
        '402':
          description: You have reached your account maximum (all matches used)
        '404':
          description: No records were found matching your request
        '405':
          description: Request method is not allowed on the requested resource
        '429':
          description: An error occurred due to requests hitting the API too quickly
      summary: /person/retrieve
      tags:
      - Person Endpoints
  /v5/person/retrieve/bulk:
    post:
      security:
      - APIKeyHeader: []
      parameters:
      - name: Content-Type
        in: header
        description: The content type
        schema:
          type: string
          default: application/json
          enum:
          - application/json
      - name: titlecase
        in: query
        description: Setting titlecase to true will titlecase the person data in 200 responses.
        schema:
          type: boolean
          default: false
      requestBody:
        description: Request object containing a list of Person IDs.
        content:
          application/json:
            schema:
              properties:
                requests:
                  type: array
                  description: requests contains a list of objects that have a Person ID and optional metadata object.
      responses:
        '200':
          description: Person Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonRetrieveBulk'
        '400':
          description: Request contained either missing or invalid parameters
        '401':
          description: Request contained a missing or invalid key
        '402':
          description: You have reached your account maximum (all matches used)
        '404':
          description: No records were found matching your request
        '405':
          description: Request method is not allowed on the requested resource
        '429':
          description: An error occurred due to requests hitting the API too quickly
      summary: /person/retrieve/bulk
      tags:
      - Person Endpoints
components:
  schemas:
    ExperienceCompany:
      type: object
      properties:
        id:
          type: string
          description: Our current NOT PERSISTENT ids that tie company data to the canonical data
        name:
          type: string
          description: The name associated with the company
        website:
          type: string
          description: The website associated with the company
        founded:
          type: string
          format: date
          description: The year that the company was founded
        size:
          type: string
          enum:
          - 1-10
          - 11-50
          - 51-200
          - 201-500
          - 501-1000
          - 1001-5000
          - 5001-10000
          - 10001+
          description: The size range of the company
        industry:
          type: string
          enum:
          - accounting
          - airlines/aviation
          - alternative dispute resolution
          - alternative medicine
          - animation
          - apparel & fashion
          - architecture & planning
          - arts and crafts
          - automotive
          - aviation & aerospace
          - banking
          - biotechnology
          - broadcast media
          - building materials
          - business supplies and equipment
          - capital markets
          - chemicals
          - civic & social organization
          - civil engineering
          - commercial real estate
          - computer & network security
          - computer games
          - computer hardware
          - computer networking
          - computer software
          - construction
          - consumer electronics
          - consumer goods
          - consumer services
          - cosmetics
          - dairy
          - defense & space
          - design
          - e-learning
          - education management
          - electrical/electronic manufacturing
          - entertainment
          - environmental services
          - events services
          - executive office
          - facilities services
          - farming
          - financial services
          - fine art
          - fishery
          - food & beverages
          - food production
          - fund-raising
          - furniture
          - gambling & casinos
          - glass, ceramics, & concrete
          - government administration
          - government relations
          - graphic design
          - health, wellness and fitness
          - higher education
          - hospital & health care
          - hospitality
          - human resources
          - import and export
          - individual & family services
          - industrial automation
          - information services
          - information technology and services
          - insurance
          - international affairs
          - international trade and development
          - internet
          - investment banking
          - investment management
          - judiciary
          - law enforcement
          - law practice
          - legal services
          - legislative office
          - leisure, travel, & tourism
          - libraries
          - logistics and supply chain
          - luxury goods & jewelry
          - machinery
          - management consulting
          - maritime
          - market research
          - marketing and advertising
          - mechanical or industrial engineering
          - media production
          - medical devices
          - medical practice
          - mental health care
          - military
          - mining & metals
          - motion pictures and film
          - museums and institutions
          - music
          - nanotechnology
          - newspapers
          - non-profit organization management
          - oil & energy
          - online media
          - outsourcing/offshoring
          - package/freight delivery
          - packaging and containers
          - paper & forest products
          - performing arts
          - pharmaceuticals
          - philanthropy
          - photography
          - plastics
          - political organization
          - primary/secondary education
          - printing
          - professional training & coaching
          - program development
          - public policy
          - public relations and communications
          - public safety
          - publishing
          - railroad manufacture
          - ranching
          - real estate
          - recreational facilities and services
          - religious institutions
          - renewables & environment
          - research
          - restaurants
          - retail
          - security and investigations
          - semiconductors
          - shipbuilding
          - sporting goods
          - sports
          - staffing and recruiting
          - supermarkets
          - telecommunications
          - textiles
          - think tanks
          - tobacco
          - translation and localization
          - transportation/trucking/railroad
          - utilities
          - venture capital & private equity
          - veterinary
          - warehousing
          - wholesale
          - wine and spirits
          - wireless
          - writing and editing
          description: The industry associated with the company
        linkedin_url:
          type: string
          description: The linkedin url associated with the company
        linkedin_id:
          type: string
          description: The linkedin id associated with the company
        facebook_url:
          type: string
          description: The facebook url associated with the company
        twitter_url:
          type: string
          description: The twitter associated with the company
        location:
          $ref: '#/components/schemas/ExperienceCompanyLocation'
    Person:
      type: object
      properties:
        id:
          type: string
          description: PDL persistent ID
        full_name:
          type: string
          description: The first and the last name fields appended with a space
        first_name:
          type: string
          description: A person's first name
        middle_initial:
          type: string
          description: A person's middle initial
        middle_name:
          type: string
          description: A person's middle name
        last_initial:
          type: string
          description: A person's last initial
        last_name:
          type: string
          description: A person's last name
        sex:
          type: string
          enum:
          - male
          - female
          description: The person's sex
        birth_year:
          type: string
          format: date
          description: Approximated birth date associated with this person profile. If a profile has a birth_date, the birth_data_fuzzy field will match
        birth_date:
          type: string
          format: date
          description: Birth date associated with this person profile
        linkedin_url:
          type: string
          format: url
          description: Main linkedin profile for this record based on source agreement
        linkedin_username:
          type: string
          description: Main linkedin username for this record based on source agreement
        linkedin_id:
          type: string
          description: Main linkedin profile id for this record based on source agreement
        facebook_url:
          type: string
          format: url
          description: facebook profile
        facebook_username:
          type: string
          description: facebook username
        facebook_id:
          type: string
          description: persistent facebook id associated with a person's facebook profile
        twitter_url:
          type: string
          format: url
          description: Twitter URL
        twitter_username:
          type: string
          description: Twitter Username
        github_url:
          type: string
          format: url
          description: Main github profile for this record based on source agreement
        github_username:
          type: string
          description: Main github profile username for this record based on source agreement
        work_email:
          type: string
          description: Current Professional email
        personal_emails:
          type: array
          description: List of all emails tagged as type = personal
          items:
            type: string
        mobile_phone:
          type: string
          description: Highly confident direct dial mobile phone associated with this person
        industry:
          type: string
          description: The most relevant industry for this record based primarily on their tagged personal industries and secondarily on the industries of the companies that they have worked for
        job_title:
          type: string
          description: A person's current job title
        job_title_role:
          type: string
          enum:
          - customer_service
          - design
          - education
          - engineering
          - finance
          - health
          - human_resources
          - legal
          - marketing
          - media
          - operations
          - public_relations
          - real_estate
          - sales
          - trades
          description: A person's current job title derived role
        job_title_sub_role:
          type: string
          enum:
          - accounting
          - accounts
          - brand_marketing
          - broadcasting
          - business_development
          - compensation
          - content_marketing
          - customer_success
          - data
          - dental
          - devops
          - doctor
          - editorial
          - education_administration
          - electrical
          - employee_development
          - events
          - fitness
          - graphic_design
          - information_technology
          - investment
          - journalism
          - judicial
          - lawyer
          - logistics
          - mechanical
          - media_relations
          - network
          - nursing
          - office_management
          - paralegal
          - pipeline
          - product
          - product_design
          - product_marketing
          - professor
          - project_engineering
          - project_management
          - property_management
          - quality_assurance
          - realtor
          - recruiting
          - researcher
          - security
          - software
       

# --- truncated at 32 KB (199 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/peopledatalabs/refs/heads/main/openapi/peopledatalabs-person-endpoints-api-openapi.yml