---
updatedAt: 2025-03-26T16:58:25.000Z
agentTools:
  projectIndex: https://docs.livedatatech.com/llms.txt
---

# Find a specific person

Find a specific person in Live Data that matches the given criteria. 

For people finding, the following fields are supported: `name`, `title`, `linkedin`, `company.name`, `company.linkedin`, `email_address`, `company.ticker`, `company.domain`, `education.school`. As many fields as are available should be sent in - the service implements a backend waterfall to find the best match(es).

The `matches` array has a max size of 100. For each item in the match array, the response array at the same index will contain all people that match the provided fields with a `score` of how well the person matches the input fields.

A maximum (and default) of 5 hits per match are provided, but can be changed. 

For queries of large groups of people, see `/search`

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0",
    "title": "Live Data People API",
    "description": "This API provides information about people as observed by Live Data",
    "termsOfService": "https://www.livedatatechnologies.com/terms-of-service",
    "contact": {
      "name": "Live Data Technologies",
      "url": "https://www.livedatatechnologies.com",
      "email": "support@livedatatechnologies.com"
    },
    "license": {
      "url": "https://creativecommons.org/licenses/by-nd/4.0",
      "name": "Attribution-NoDerivs"
    }
  },
  "servers": [
    {
      "url": "https://gotlivedata.io/api/people/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "AccessToken": []
    }
  ],
  "tags": [
    {
      "name": "Search"
    }
  ],
  "paths": {
    "/{org_id}/find": {
      "parameters": [
        {
          "schema": {
            "type": "string"
          },
          "name": "org_id",
          "in": "path",
          "required": true,
          "description": "Your Org ID"
        }
      ],
      "post": {
        "summary": "Find a specific person",
        "operationId": "find",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "matches": {
                      "type": "array",
                      "x-stoplight": {
                        "id": "1ishbiluhaal7"
                      },
                      "description": "An array of responses. Each position in the array corresponds to the position in the input array.",
                      "items": {
                        "x-stoplight": {
                          "id": "lwpt53p6al6ae"
                        },
                        "type": "object",
                        "properties": {
                          "people": {
                            "type": "array",
                            "x-stoplight": {
                              "id": "on0hebz46wh7f"
                            },
                            "description": "The people that matched the provided filters. Maximum of 5 returned in this endpoint (use `/search` for larger queries).",
                            "items": {
                              "x-stoplight": {
                                "id": "9vloefkwodpjg"
                              },
                              "allOf": [
                                {
                                  "$ref": "#/components/schemas/Person"
                                },
                                {
                                  "type": "object",
                                  "x-stoplight": {
                                    "id": "qtxz3rqd5w4gr"
                                  },
                                  "properties": {
                                    "score": {
                                      "type": "number",
                                      "x-stoplight": {
                                        "id": "17i42b6zcnfsk"
                                      },
                                      "description": "A score of how well each person matched the input criteria."
                                    }
                                  }
                                }
                              ]
                            }
                          },
                          "found": {
                            "type": "boolean",
                            "x-stoplight": {
                              "id": "y0h8t00jzu11p"
                            },
                            "description": "Indicates whether there was at least one hit given the provided inputs."
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "Example 1": {
                    "value": {
                      "matches": [
                        {
                          "people": [
                            {
                              "id": "string",
                              "created_at": "string",
                              "info_change_detected_at": "string",
                              "title_change_detected_at": "string",
                              "company_change_detected_at": "string",
                              "position": {
                                "title": "string",
                                "level": "C-Team",
                                "function": "Banking and Wealth Management",
                                "started_at": "string",
                                "started_at_year_only": true,
                                "ended_at": "string",
                                "ended_at_year_only": true,
                                "location": "string",
                                "email": "string",
                                "email_status": "valid",
                                "direct_dial_number": "string",
                                "company": {
                                  "id": "string",
                                  "name": "string",
                                  "location": "string",
                                  "linkedin": "string",
                                  "ticker": "string",
                                  "type": "Privately Held",
                                  "address": "string",
                                  "country": "string",
                                  "domain": "string",
                                  "employee_count": 0,
                                  "industry": "string",
                                  "sic_codes": [
                                    "string"
                                  ]
                                }
                              },
                              "jobs": {
                                "title": "string",
                                "level": "C-Team",
                                "function": "Banking and Wealth Management",
                                "started_at": "string",
                                "started_at_year_only": true,
                                "ended_at": "string",
                                "ended_at_year_only": true,
                                "location": "string",
                                "email": "string",
                                "email_status": "valid",
                                "direct_dial_number": "string",
                                "company": {
                                  "id": "string",
                                  "name": "string",
                                  "location": "string",
                                  "linkedin": "string",
                                  "ticker": "string",
                                  "type": "Privately Held",
                                  "address": "string",
                                  "country": "string",
                                  "domain": "string",
                                  "employee_count": 0,
                                  "industry": "string",
                                  "sic_codes": [
                                    "string"
                                  ]
                                }
                              },
                              "education": [
                                {
                                  "school": "string",
                                  "field": "string",
                                  "degree": "string",
                                  "started_at": "string",
                                  "ended_at": "string"
                                }
                              ],
                              "first_name": "string",
                              "last_name": "string",
                              "name": "string",
                              "linkedin": "string",
                              "country": "string",
                              "connections": "string",
                              "location": "string",
                              "cell_phone_number": "string",
                              "score": 0
                            }
                          ]
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment Required"
          }
        },
        "x-stoplight": {
          "id": "9e3k2dwbw1kz7"
        },
        "tags": [
          "Search"
        ],
        "description": "Find a specific person in Live Data that matches the given criteria. \r\n\r\nFor people finding, the following fields are supported: `name`, `title`, `linkedin`, `company.name`, `company.linkedin`, `email_address`, `company.ticker`, `company.domain`, `education.school`. As many fields as are available should be sent in - the service implements a backend waterfall to find the best match(es).\r\n\r\nThe `matches` array has a max size of 100. For each item in the match array, the response array at the same index will contain all people that match the provided fields with a `score` of how well the person matches the input fields.\r\n\r\nA maximum (and default) of 5 hits per match are provided, but can be changed. \r\n\r\nFor queries of large groups of people, see `/search`",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "matches": {
                    "type": "array",
                    "x-stoplight": {
                      "id": "hk6uiggvij93b"
                    },
                    "items": {
                      "x-stoplight": {
                        "id": "l2w1hyoq5lq1i"
                      },
                      "type": "object",
                      "properties": {
                        "fields": {
                          "type": "array",
                          "x-stoplight": {
                            "id": "hnz19bgw9591d"
                          },
                          "items": {
                            "x-stoplight": {
                              "id": "ydx9wwc3ho3ak"
                            },
                            "type": "object",
                            "properties": {
                              "field_name": {
                                "type": "string",
                                "x-stoplight": {
                                  "id": "7u93kwuxa1ap0"
                                }
                              },
                              "search_term": {
                                "type": "string",
                                "x-stoplight": {
                                  "id": "t1affhqveqr6f"
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  },
                  "size": {
                    "type": "integer",
                    "x-stoplight": {
                      "id": "flwrf97b163da"
                    },
                    "maximum": 5
                  },
                  "return_fields": {
                    "type": "array",
                    "x-stoplight": {
                      "id": "keli1gokilhax"
                    },
                    "items": {
                      "x-stoplight": {
                        "id": "txl9ujvnfc1ww"
                      },
                      "type": "string"
                    }
                  },
                  "confidence": {
                    "type": "string",
                    "x-stoplight": {
                      "id": "c7gj92hb5loe9"
                    }
                  }
                }
              },
              "examples": {
                "Example 1": {
                  "value": {
                    "matches": [
                      {
                        "fields": [
                          {
                            "field_name": "email_address",
                            "search_term": "joe@google.com"
                          }
                        ]
                      },
                      {
                        "fields": [
                          {
                            "field_name": "email_address",
                            "search_term": "joe@amazon.com"
                          }
                        ]
                      }
                    ]
                  }
                }
              }
            }
          },
          "description": ""
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "AccessToken": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Person": {
        "title": "Person",
        "x-stoplight": {
          "id": "85licuviag53x"
        },
        "type": "object",
        "description": "Represents a Person as observed by Live Data.",
        "properties": {
          "id": {
            "type": "string",
            "x-stoplight": {
              "id": "k311negf93agi"
            },
            "description": "The unique Live Data ID for this person"
          },
          "created_at": {
            "type": "string",
            "x-stoplight": {
              "id": "sgu2pr5fvpkjk"
            },
            "description": "Date the person was added to Live Data"
          },
          "info_change_detected_at": {
            "type": "string",
            "x-stoplight": {
              "id": "23jpmsp9yvdmv"
            },
            "description": "Most recent date that any field changed."
          },
          "title_change_detected_at": {
            "type": "string",
            "x-stoplight": {
              "id": "lj6dwzekz7qza"
            },
            "description": "Most recent date that Live Data detected a title change."
          },
          "company_change_detected_at": {
            "type": "string",
            "x-stoplight": {
              "id": "23j6m3c40438l"
            },
            "description": "Most recent date that Live Data detected a company change."
          },
          "position": {
            "$ref": "#/components/schemas/Job"
          },
          "jobs": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Job"
            }
          },
          "education": {
            "type": "array",
            "x-stoplight": {
              "id": "dv77kigmrp97g"
            },
            "description": "Array of the education history for this person",
            "items": {
              "x-stoplight": {
                "id": "hk63h7w0y1uug"
              },
              "type": "object",
              "properties": {
                "school": {
                  "type": "string",
                  "x-stoplight": {
                    "id": "as9oiysbjinuo"
                  },
                  "description": "Name of the school"
                },
                "field": {
                  "type": "string",
                  "x-stoplight": {
                    "id": "pd2xfiff9aygn"
                  },
                  "description": "Name of the field of study"
                },
                "degree": {
                  "type": "string",
                  "x-stoplight": {
                    "id": "yj2b0ut87cqxc"
                  },
                  "description": "Name of the degree the person achieved"
                },
                "started_at": {
                  "type": "string",
                  "x-stoplight": {
                    "id": "t98nbsrb6nwmj"
                  },
                  "description": "Started at date. Will always be the 1st day of a month at 00:00"
                },
                "ended_at": {
                  "type": "string",
                  "x-stoplight": {
                    "id": "70km7qhfhyaml"
                  },
                  "description": "Ended at date. Will always be the 1st day of a month at 00:00"
                }
              }
            }
          },
          "first_name": {
            "type": "string",
            "x-stoplight": {
              "id": "naiw447a8eg5c"
            },
            "description": "First name, if known"
          },
          "last_name": {
            "type": "string",
            "x-stoplight": {
              "id": "lc63xpw9h5b8v"
            },
            "description": "Last name, if known"
          },
          "name": {
            "type": "string",
            "x-stoplight": {
              "id": "ar1wo62unv6aa"
            },
            "description": "Name of the person"
          },
          "linkedin": {
            "type": "string",
            "x-stoplight": {
              "id": "8ast25rbdbxrd"
            },
            "description": "The linkedin ID for this person"
          },
          "country": {
            "type": "string",
            "x-stoplight": {
              "id": "b15lhbdx19x6i"
            },
            "description": "Name of the country this person lives in"
          },
          "connections": {
            "type": "integer",
            "x-stoplight": {
              "id": "9jcs8j1rxxqs6"
            },
            "description": "Number of connections on LinkedIn"
          },
          "location": {
            "type": "string",
            "x-stoplight": {
              "id": "tvsto3jviyvx0"
            },
            "description": "Location of this person"
          },
          "cell_phone_number": {
            "type": "string",
            "x-stoplight": {
              "id": "94pxj3vmya6kz"
            },
            "description": "Person’s cell phone number"
          },
          "location_details": {
            "$ref": "#/components/schemas/LocationDetails"
          },
          "employment_status": {
            "x-stoplight": {
              "id": "xp5epbekvwvcp"
            },
            "enum": [
              "employed",
              "unemployed",
              "retired"
            ]
          }
        }
      },
      "Job": {
        "title": "Job",
        "x-stoplight": {
          "id": "uyf2420n56xl0"
        },
        "type": "object",
        "description": "Represents a job, which is a combination of Company+Title",
        "properties": {
          "title": {
            "type": "string",
            "x-stoplight": {
              "id": "xa7rcb1zvi4vm"
            },
            "description": "Title of the person at this job"
          },
          "level": {
            "x-stoplight": {
              "id": "91yw8tt23adwn"
            },
            "description": "Level derived from title using internal ML process",
            "enum": [
              "C-Team",
              "VP",
              "Director",
              "Manager",
              "Staff",
              "Senior Staff",
              "Intern",
              "Consultant"
            ]
          },
          "function": {
            "x-stoplight": {
              "id": "livsv0yno1xzt"
            },
            "description": "Function derived from title using internal ML process",
            "enum": [
              "Banking and Wealth Management",
              "Business Management",
              "Consulting",
              "Education",
              "Engineering",
              "Finance and Administration",
              "Healthcare",
              "Human Resources",
              "Information Technology",
              "Legal",
              "Marketing and Product",
              "Operations",
              "Program and Project Management",
              "Publishing, Editorial and Reporting",
              "Quality",
              "Real Estate",
              "Risk, Safety, Compliance",
              "Sales and Support"
            ]
          },
          "started_at": {
            "type": "string",
            "x-stoplight": {
              "id": "fnk2tl5tlpzqj"
            },
            "description": "Date the person started this job. Will always be the 1st day of a month at 00:00"
          },
          "started_at_year_only": {
            "type": "boolean",
            "x-stoplight": {
              "id": "f9j4mnbq4i2y8"
            },
            "description": "Indicates if the started_at date should be parsed as a year only. In these cases, the date will always be Jan 1."
          },
          "ended_at": {
            "type": "string",
            "x-stoplight": {
              "id": "aq0arof2wg4zh"
            },
            "description": "Date this job ended. Will always be the 1st day of a month at 00:00"
          },
          "ended_at_year_only": {
            "type": "boolean",
            "x-stoplight": {
              "id": "qtcvlc8uym6d8"
            },
            "description": "Indicates if the ended_at date should be parsed as a year only. In these cases, the date will always be Jan 1."
          },
          "location": {
            "type": "string",
            "x-stoplight": {
              "id": "7kgrclmxeg8tx"
            },
            "description": "Location of this job"
          },
          "email": {
            "type": "string",
            "x-stoplight": {
              "id": "jr2vcj0g228h"
            },
            "description": "Person’s email address at this job"
          },
          "email_status": {
            "x-stoplight": {
              "id": "rllrrudjccise"
            },
            "description": "Status of their email at this job",
            "enum": [
              "valid",
              "catch-all",
              "best-guess"
            ]
          },
          "direct_dial_number": {
            "type": "string",
            "x-stoplight": {
              "id": "sjnjn1a5cdun2"
            },
            "description": "Person’s phone number at this job"
          },
          "company": {
            "$ref": "#/components/schemas/Company"
          },
          "location_details": {
            "$ref": "#/components/schemas/LocationDetails"
          },
          "duration": {
            "type": "integer",
            "x-stoplight": {
              "id": "5r8ltawt7dhe9"
            },
            "description": "The duration of this particular job, in months"
          },
          "company_tenure": {
            "type": "integer",
            "x-stoplight": {
              "id": "h5lfvv4l046x5"
            },
            "description": "The tenure of the person at this company, across contiguous jobs, in months"
          },
          "is_first_at_company": {
            "type": "boolean",
            "x-stoplight": {
              "id": "4ccyfo2nmggh4"
            },
            "description": "Boolean value to indicate whether this is the person’s first job at this company"
          },
          "is_last_at_company": {
            "type": "boolean",
            "x-stoplight": {
              "id": "xix4tmke68o8t"
            },
            "description": "Boolean value to indicate whether this is the person’s last job at this company. Note this will be `true` for active jobs."
          }
        }
      },
      "Company": {
        "title": "Company",
        "x-stoplight": {
          "id": "zlr8vcxxg4jff"
        },
        "type": "object",
        "description": "Dict of company-specific information related to the job",
        "properties": {
          "id": {
            "type": "string",
            "x-stoplight": {
              "id": "6c9jqtivsxz5f"
            },
            "description": "Unique Live Data ID for this company"
          },
          "name": {
            "type": "string",
            "x-stoplight": {
              "id": "dj9i13fkldtuy"
            },
            "description": "Name of the company"
          },
          "location": {
            "type": "string",
            "x-stoplight": {
              "id": "yqdea3bad734g"
            },
            "description": "Primary general locality of the business"
          },
          "linkedin": {
            "type": "string",
            "x-stoplight": {
              "id": "s01tn7uhvt8pk"
            },
            "description": "LinkedIn slug for the company"
          },
          "ticker": {
            "type": "string",
            "x-stoplight": {
              "id": "8edqt1w8fj143"
            },
            "description": "Public stock ticker for the company, if applicable"
          },
          "type": {
            "x-stoplight": {
              "id": "yla5fph6fow6u"
            },
            "description": "Company type (public, private, govt, non-profit, etc)",
            "enum": [
              "Privately Held",
              "Self Owned",
              "Non Profit",
              "Public Company",
              "Partnership",
              "Self Employed",
              "Educational",
              "Government Agency"
            ]
          },
          "address": {
            "type": "string",
            "x-stoplight": {
              "id": "bi299z9lxfk4p"
            },
            "description": "Primary street address"
          },
          "country": {
            "type": "string",
            "x-stoplight": {
              "id": "nnfye4wdoh6f7"
            },
            "description": "Primary country for this company"
          },
          "domain": {
            "type": "string",
            "x-stoplight": {
              "id": "gj113pjln6jq1"
            },
            "description": "Primary domain for the company"
          },
          "employee_count": {
            "type": "number",
            "x-stoplight": {
              "id": "8qnv95v0eaa9v"
            },
            "description": "Total employee count"
          },
          "industry": {
            "type": "string",
            "x-stoplight": {
              "id": "ptn4a6ob2jpc1"
            },
            "description": "Primary industry"
          },
          "sic_codes": {
            "type": "array",
            "x-stoplight": {
              "id": "d8poc34ml84ay"
            },
            "description": "SIC codes",
            "items": {
              "x-stoplight": {
                "id": "6guysie6l87za"
              },
              "type": "string"
            }
          },
          "ultimate_parent": {
            "$ref": "#/components/schemas/UltimateParentCompany"
          }
        }
      },
      "LocationDetails": {
        "title": "LocationDetails",
        "x-stoplight": {
          "id": "8tuj0x6z3nwfa"
        },
        "type": "object",
        "properties": {
          "country": {
            "type": "string",
            "x-stoplight": {
              "id": "accjsfwmpmcln"
            },
            "description": "The normalized country name for this location"
          },
          "country_code": {
            "type": "string",
            "x-stoplight": {
              "id": "loxlq0ye958dp"
            },
            "description": "The two-letter ISO country code for this location"
          },
          "region": {
            "type": "string",
            "x-stoplight": {
              "id": "ylrbr3x80tigt"
            },
            "description": "The normalized region name for this location. For US locations, this is the State"
          },
          "region_abbreviation": {
            "type": "string",
            "x-stoplight": {
              "id": "m7z3gpnh3wwis"
            },
            "description": "The standard abbreviation for the normalized region "
          },
          "locality": {
            "type": "string",
            "x-stoplight": {
              "id": "hgrzl0mb3qee5"
            },
            "description": "The normalized locality name for this location. For US locations, this is the City"
          },
          "county": {
            "type": "string",
            "x-stoplight": {
              "id": "ekjxpyztok7hf"
            },
            "description": "For US locations, the county name for this location"
          },
          "postal_code": {
            "type": "string",
            "x-stoplight": {
              "id": "1rj0z0vsi5opp"
            },
            "description": "The central/primary postal code associated with this location. For US locations, this is the 5-digit zip code"
          },
          "msa": {
            "type": "string",
            "x-stoplight": {
              "id": "9a5a0omqviydu"
            },
            "description": "For US locations, the standard MSA name that this location belongs to, if any"
          },
          "lat": {
            "type": "string",
            "x-stoplight": {
              "id": "z6xc45yx6nvh8"
            },
            "description": "The latitude for this location, generalized"
          },
          "lon": {
            "type": "string",
            "x-stoplight": {
              "id": "f8o5jkv8cnkto"
            },
            "description": "The longitude for this location, generalized"
          },
          "fips_code": {
            "type": "string",
            "x-stoplight": {
              "id": "pxaipjepvoo55"
            },
            "description": "The FIPS code for this location"
          },
          "raw": {
            "type": "string",
            "x-stoplight": {
              "id": "2il2ndf5use5w"
            },
            "description": "The input location value from which the other values were derived"
          }
        }
      },
      "UltimateParentCompany": {
        "title": "UltimateParentCompany",
        "x-stoplight": {
          "id": "b3qhpu3l5w2mj"
        },
        "type": "object",
        "description": "Ultimate Parent Company",
        "properties": {
          "id": {
            "type": "string",
            "x-stoplight": {
              "id": "ie8nt15n84zcb"
            }
          },
          "name": {
            "type": "string",
            "x-stoplight": {
              "id": "w29c68mai7iya"
            }
          },
          "linkedin": {
            "type": "string",
            "x-stoplight": {
              "id": "jyj4tthd698ma"
            }
          },
          "ticker": {
            "type": "string",
            "x-stoplight": {
              "id": "004ay2mbb3st9"
            }
          },
          "domain": {
            "type": "string",
            "x-stoplight": {
              "id": "8mo0kfwxq9f79"
            }
          }
        }
      }
    }
  }
}
```