People Data Labs Person API

openapi: 3.2.0
info:
  title: Peopledatalabs Person API
  version: '1.0'
  description: 'Operations tagged Person across 2 of this provider''s published API definitions: peopledatalabs-docs-openapi.json, peopledatalabs-person-api-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.peopledatalabs.com
- url: http://api.peopledatalabs.com
- url: https://api.peopledatalabs.com/v5
  description: People Data Labs production API
tags:
- name: Person
paths:
  /v5/person/subjectrequest:
    get:
      summary: /v5/person/subjectrequest
      description: Retrieves a CSV file containing the PDL Person IDs that have Opt-ed out of our data.
      security:
      - APIKeyHeader: []
      parameters: []
      responses:
        '200':
          description: List of PDL IDs to be deleted.
        '503':
          description: Internal Error of our systems.
      tags:
      - Person
      operationId: getV5PersonSubjectrequest
      x-operation-id-source: derived
    servers:
    - url: https://api.peopledatalabs.com
    - url: http://api.peopledatalabs.com
  /v5/person/enrich:
    get:
      tags:
      - Person
      summary: /person/enrich
      description: Enrich a person record on a variety of fields
      security:
      - APIKeyHeader: []
      parameters:
      - name: pdl_id
        in: query
        description: PDL's Person ID value. If provided, it will be the only input used
        schema:
          type: string
      - name: name
        in: query
        description: The person's full name, at least first and last
        schema:
          type: string
      - name: first_name
        in: query
        description: The person's first name
        schema:
          type: string
      - name: last_name
        in: query
        description: The person's last name
        schema:
          type: string
      - name: middle_name
        in: query
        description: The person's middle name
        schema:
          type: string
      - name: location
        in: query
        description: A location in which a person lives
        schema:
          type: string
      - name: street_address
        in: query
        description: A street address in which the person lives
        schema:
          type: string
      - name: locality
        in: query
        description: A locality in which the person lives
        schema:
          type: string
      - name: region
        in: query
        description: A state or region in which the person lives
        schema:
          type: string
      - name: country
        in: query
        description: A country in which the person lives
        schema:
          type: string
      - name: postal_code
        in: query
        description: The postal code in which the person lives
        schema:
          type: string
      - name: company
        in: query
        description: A name, website, or social url of a company where the person has worked
        schema:
          type: string
      - name: school
        in: query
        description: A name, website, or social url of a university or college the person has attended
        schema:
          type: string
      - name: phone
        in: query
        description: A phone number the person has used
        schema:
          type: string
      - name: email
        in: query
        description: An email the person has used
        schema:
          type: string
      - name: email_hash
        in: query
        description: A sha256 email hash
        schema:
          type: string
      - name: profile
        in: query
        description: A social profile the person has used. https://docs.peopledatalabs.com/docs/social-networks
        schema:
          type: string
      - name: lid
        in: query
        description: A LinkedIn numerical ID
        schema:
          type: string
      - name: birth_date
        in: query
        description: The person's birth date. Either the year, or a full birth date
        schema:
          type: string
      - name: min_likelihood
        in: query
        description: The minimum likelihood score a response must possess in order to return a 200
        schema:
          type: integer
          maximum: 10
          minimum: 0
          format: int32
          default: 0
      - name: required
        in: query
        description: Parameter specifying the fields and data points a response must have to return a 200
        schema:
          type: string
      - 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. eg. "names.clean,emails.address". 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
      - 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
      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 quick
      operationId: getV5PersonEnrich
      x-operation-id-source: derived
    servers:
    - url: https://api.peopledatalabs.com
    - url: http://api.peopledatalabs.com
  /v5/person/enrich/preview:
    get:
      tags:
      - Person
      summary: /person/enrich/preview
      description: Enrich a person record on a variety of fields and receive a preview record in return
      security:
      - APIKeyHeader: []
      parameters:
      - name: name
        in: query
        description: The person's full name, at least first and last
        schema:
          type: string
      - name: first_name
        in: query
        description: The person's first name
        schema:
          type: string
      - name: last_name
        in: query
        description: The person's last name
        schema:
          type: string
      - name: middle_name
        in: query
        description: The person's middle name
        schema:
          type: string
      - name: location
        in: query
        description: A location in which a person lives
        schema:
          type: string
      - name: street_address
        in: query
        description: A street address in which the person lives
        schema:
          type: string
      - name: locality
        in: query
        description: A locality in which the person lives
        schema:
          type: string
      - name: region
        in: query
        description: A state or region in which the person lives
        schema:
          type: string
      - name: country
        in: query
        description: A country in which the person lives
        schema:
          type: string
      - name: postal_code
        in: query
        description: The postal code in which the person lives
        schema:
          type: string
      - name: company
        in: query
        description: A name, website, or social url of a company where the person has worked
        schema:
          type: string
      - name: school
        in: query
        description: A name, website, or social url of a university or college the person has attended
        schema:
          type: string
      - name: phone
        in: query
        description: A phone number the person has used
        schema:
          type: string
      - name: email
        in: query
        description: An email the person has used
        schema:
          type: string
      - name: email_hash
        in: query
        description: A sha256 email hash
        schema:
          type: string
      - name: profile
        in: query
        description: A social profile the person has used. https://docs.peopledatalabs.com/docs/social-networks
        schema:
          type: string
      - name: lid
        in: query
        description: A LinkedIn numerical ID
        schema:
          type: string
      - name: birth_date
        in: query
        description: The person's birth date. Either the year, or a full birth date
        schema:
          type: string
      - name: min_likelihood
        in: query
        description: The minimum likelihood score a response must possess in order to return a 200
        schema:
          type: integer
          maximum: 10
          minimum: 0
          format: int32
          default: 0
      - name: required
        in: query
        description: Parameter specifying the fields and data points a response must have to return a 200
        schema:
          type: string
      - name: titlecase
        in: query
        description: Setting titlecase to true will titlecase the person data in 200 responses.
        schema:
          type: boolean
          default: false
      - 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
      responses:
        '200':
          description: Person Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonPreview'
        '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 quick
      operationId: getV5PersonEnrichPreview
      x-operation-id-source: derived
    servers:
    - url: https://api.peopledatalabs.com
    - url: http://api.peopledatalabs.com
  /v5/person/identify:
    get:
      tags:
      - Person
      summary: /person/identify
      description: Recover all related profiles for an identity
      security:
      - APIKeyHeader: []
      parameters:
      - name: name
        in: query
        description: The person's full name, at least first and last
        schema:
          type: string
      - name: first_name
        in: query
        description: The person's first name
        schema:
          type: string
      - name: last_name
        in: query
        description: The person's last name
        schema:
          type: string
      - name: middle_name
        in: query
        description: The person's middle name
        schema:
          type: string
      - name: location
        in: query
        description: A location in which a person lives
        schema:
          type: string
      - name: street_address
        in: query
        description: A street address in which the person lives
        schema:
          type: string
      - name: locality
        in: query
        description: A locality in which the person lives
        schema:
          type: string
      - name: region
        in: query
        description: A state or region in which the person lives
        schema:
          type: string
      - name: country
        in: query
        description: A country in which the person lives
        schema:
          type: string
      - name: postal_code
        in: query
        description: The postal code in which the person lives
        schema:
          type: string
      - name: company
        in: query
        description: A name, website, or social url of a company where the person has worked
        schema:
          type: string
      - name: school
        in: query
        description: A name, website, or social url of a university or college the person has attended
        schema:
          type: string
      - name: phone
        in: query
        description: A phone number the person has used
        schema:
          type: string
      - name: email
        in: query
        description: An email the person has used
        schema:
          type: string
      - name: email_hash
        in: query
        description: A sha256 email hash
        schema:
          type: string
      - name: profile
        in: query
        description: A social profile the person has used. https://docs.peopledatalabs.com/docs/social-networks
        schema:
          type: string
      - name: lid
        in: query
        description: A LinkedIn numerical ID
        schema:
          type: string
      - name: birth_date
        in: query
        description: The person's birth date. Either the year, or a full birth date
        schema:
          type: string
      - name: min_likelihood
        in: query
        description: The minimum likelihood score a response must possess in order to return a 200
        schema:
          type: integer
          maximum: 10
          minimum: 0
          format: int32
          default: 0
      - name: required
        in: query
        description: Parameter specifying the fields and data points a response must have to return a 200
        schema:
          type: string
      - 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. eg. "names.clean,emails.address". 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
      - 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
      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 quick
      operationId: getV5PersonIdentify
      x-operation-id-source: derived
    servers:
    - url: https://api.peopledatalabs.com
    - url: http://api.peopledatalabs.com
  /v5/person/search:
    get:
      tags:
      - Person
      summary: /person/search
      description: Search People Data Labs Dataset
      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.
        schema:
          type: string
      - 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 PDL fields. Any use of column selections or the LIMIT keyword will be ignored.'
        schema:
          type: string
      - 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: from
        in: query
        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
        schema:
          type: integer
          maximum: 9999
          minimum: 0
          format: int32
          default: 0
      - 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
          default: ''
      - name: titlecase
        in: query
        description: Setting titlecase to true will titlecase any records returned
        schema:
          type: boolean
          default: false
      - name: pretty
        in: query
        description: Whether the output should have human-readable indentation.
        schema:
          type: boolean
          default: false
      - 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
      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 quick
      operationId: getV5PersonSearch
      x-operation-id-source: derived
    post:
      tags:
      - Person
      summary: /person/search
      description: Search People Data Labs Dataset
      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.
        schema:
          type: string
      - 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 PDL fields. Any use of column selections or the LIMIT keyword will be ignored.'
        schema:
          type: string
      - name: size
        in: query
        description: The number of matched records to return for this query if they exist*. Must be between 1 and 1000 (inclusive)
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          format: int32
          default: 1
      - name: from
        in: query
        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
        schema:
          type: integer
          maximum: 9999
          minimum: 0
          format: int32
          default: 0
      - 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
          default: ''
      - name: titlecase
        in: query
        description: Setting titlecase to true will titlecase any records returned
        schema:
          type: boolean
          default: false
      - name: pretty
        in: query
        description: Whether the output should have human-readable indentation.
        schema:
          type: boolean
          default: false
      - 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
      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 quick
      operationId: postV5PersonSearch
      x-operation-id-source: derived
    servers:
    - url: https://api.peopledatalabs.com
    - url: http://api.peopledatalabs.com
  /v5/person/retrieve/{person_id}:
    get:
      tags:
      - Person
      summary: /person/retrieve/
      description: Retrieves a person based on a PDL ID.
      security:
      - APIKeyHeader: []
      parameters:
      - 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
      - name: filter_updated
        in: query
        description: Filter out results that have not been updated since the most recent request based on the given key or keys (comma delimited)
        schema:
          type: string
          enum:
          - job_change,location
      - name: request_version
        in: query
        description: Allows for a specific version of a filter_update, bypassing the `last_requested_version`
        schema:
          type: string
      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 quick
      operationId: getV5PersonRetrieveByPersonId
      x-operation-id-source: derived
    servers:
    - url: https://api.peopledatalabs.com
    - url: http://api.peopledatalabs.com
  /v5/person/retrieve/bulk:
    post:
      tags:
      - Person
      summary: /person/retrieve/bulk
      description: Retrieves up to 100 person records based on a PDL ID.
      security:
      - APIKeyHeader: []
      parameters:
      - name: titlecase
        in: query
        description: Setting titlecase to true will titlecase the person data in 200 responses.
        schema:
          type: boolean
          default: false
      - name: filter_updated
        in: query
        description: Filter out results that have not been updated since the most recent request based on the given key
        schema:
          type: string
          enum:
          - job_change
      - name: request_version
        in: query
        description: Allows for a specific version of a filter_update, bypassing the `last_requested_version`
        schema:
          type: string
      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 quick
      operationId: postV5PersonRetrieveBulk
      x-operation-id-source: derived
    servers:
    - url: https://api.peopledatalabs.com
    - url: http://api.peopledatalabs.com
  /person/enrich:
    servers:
    - url: https://api.peopledatalabs.com/v5
      description: People Data Labs production API
    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.
      security:
      - ApiKeyAuth: []
      operationId: getPersonEnrich
      x-operation-id-source: derived
  /person/search:
    servers:
    - url: https://api.peopledatalabs.com/v5
      description: People Data Labs production API
    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.
      security:
      - ApiKeyAuth: []
      operationId: getPersonSearch
      x-operation-id-source: derived
  /person/identify:
    servers:
    - url: https://api.peopledatalabs.com/v5
      description: People Data Labs production API
    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.
      security:
      - ApiKeyAuth: []
      operationId: getPersonIdentify
      x-operation-id-source: derived
  /person/bulk:
    servers:
    - url: https://api.peopledatalabs.com/v5
      description: People Data Labs production API
    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.
      security:
      - ApiKeyAuth: []
      operationId: postPersonBulk
      x-operation-id-source: derived
components:
  schemas:
    StreetAddress:
      type: object
      properties:
        street_address:
          type: string
          description: The street address associated with the location object
        address_line_2:
          type: string
          description: The secondary street address associated with the location object
        name:
          type: string
          description: A string that appends location fields together to create a standard location field
        locality:
          type: string
          description: The administrative locality associated with the location object
        metro:
          type: string
          description: The metro area associated with the location object
        region:
          type: string
          description: The administrative region associated with the location object
        postal_code:
          type: string
          description: The postal code associated with the location object
        country:
          type: string
          description: The country associated with the location object
        geo:
          type: string
          description: The geolocation associated with the location object in latitude, longitude format
        continent:
          type: string
          description: The continent associated with the country in the location object
      additionalProperties: false
    ExperienceCompanyLocation:
      type: object
      properties:
        street_address:
          type: string
          description: Company HQ address
        address_line_2:
          type: string
          description: The address line 2 associated with the company HQ
        name:
          type: string
          description: The canonical location name associated with the company HQ
        locality:
          type: string
          description: Company locality
        metro:
          type: string
          description: Company metro area
        region:
          type: string
          description: Company region
        country:
          type: string
          descripti

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