--- updatedAt: 2025-03-26T16:58:25.000Z agentTools: projectIndex: https://docs.livedatatech.com/llms.txt --- # Search for collections of people Search for people in Live Data that match the specified filters. # 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}/search": { "post": { "summary": "Search for collections of people", "operationId": "search-persons-data", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "people": { "type": "array", "x-stoplight": { "id": "4by1cxlalbq4a" }, "description": "An array of all the matching people based on the provided filters and size.", "items": { "$ref": "#/components/schemas/Person" } }, "pagination_token": { "type": "string", "x-stoplight": { "id": "or3ubqoojgbaq" }, "description": "If provided, make the exact same call with this added parameter to get the next page of results based on your existing filters and size. \r\n\r\nIf not provided, no additional contacts match the given criteria." }, "count": { "type": "integer", "x-stoplight": { "id": "qdk53kujeco3h" } }, "aggs": { "type": "array", "x-stoplight": { "id": "p9fifcb88pfdy" }, "items": { "$ref": "#/components/schemas/AggResponse" } }, "report_results": { "type": "object", "x-stoplight": { "id": "sx0cs0ncmlxzi" } } } } } } }, "402": { "description": "Payment Required", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "x-stoplight": { "id": "7dzctagy257rs" } } } } } } } }, "tags": [ "Search" ], "description": "Search for people in Live Data that match the specified filters. ", "x-stoplight": { "id": "tu8zkz1akfja4" }, "requestBody": { "$ref": "#/components/requestBodies/PersonSearchBody" } }, "parameters": [ { "schema": { "type": "string" }, "name": "org_id", "in": "path", "required": true, "description": "Your Org ID" } ] } }, "components": { "securitySchemes": { "AccessToken": { "type": "http", "scheme": "bearer" } }, "schemas": { "SearchFilter": { "title": "SearchFilter", "x-stoplight": { "id": "5dnlx7l5afx9d" }, "type": "object", "properties": { "type": { "type": "string", "enum": [ "must", "must_not" ], "description": "Either 'must' or 'must_not'" }, "field": { "type": "string", "description": "The name of the field in OS" }, "string_values": { "type": "array", "description": "If the field is a text field, an array of values that must/must-not match", "items": { "type": "string" } }, "date_from": { "type": "string", "description": "If the field is a date field, this is the \"from\" date to use" }, "date_to": { "type": "string", "description": "If the field is a date field, this is the \"to\" date to use" }, "number_min": { "type": "number", "description": "If the field is a number field, the min number tha t must match" }, "number_max": { "type": "number", "description": "If the field is a number field, the max number tha t must match" }, "boolean_value": { "type": "boolean", "description": "If the field is a boolean, this value will be used for the filter" }, "match_type": { "type": "string", "enum": [ "fuzzy", "exact", "exists" ], "default": "fuzzy", "description": "Specifies what kind of match to do on the field: \n* `fuzzy` - match the value in a fuzzy manner\n* `exact` - match the value exactly\n* `exists` - only query the existence of the field, not a value match\n\n`fuzzy` and `exact` only apply to string fields, not dates, numbers, or bools" } } }, "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" } } }, "FilterGroup": { "title": "FilterGroup", "x-stoplight": { "id": "83piui1w831kr" }, "type": "object", "description": "Provides a group of filters that are either `and`ed or `or`ed together.\n\nIf a FilterGroup contains any filter on `jobs`, then all filters in that FilterGroup must be `jobs` filters. A jobs filter group may contain `aggs` to aggregate data that matches only the jobs that match those filters. \n\nA non-jobs filter group can not contain `aggs` - use the root-level `aggs` to aggregate across all data.\n\nOnly `report` is allowed per request. It can be at the top-level to report across all data or within a \"jobs\" filter group to report only on that cohort. No matter the location of the `report` in the request, the data is always provided at the top-level `report_data`. The `report_data` is only reported on the first page of results, subsequent pages will not contain the data.", "properties": { "operator": { "x-stoplight": { "id": "tev53dgea60ml" }, "enum": [ "and", "or" ] }, "filters": { "type": "array", "x-stoplight": { "id": "5xmrupsdah7cf" }, "items": { "x-stoplight": { "id": "g9inzjstn8lkt" }, "anyOf": [ { "$ref": "#/components/schemas/SearchFilter" }, { "$ref": "#/components/schemas/FilterGroup" } ] } }, "aggs": { "type": "array", "x-stoplight": { "id": "h1qnen96bt3ze" }, "items": { "$ref": "#/components/schemas/AggRequest" } }, "report": { "$ref": "#/components/schemas/SearchReportRequest" } } }, "AggRequest": { "title": "AggRequest", "x-stoplight": { "id": "jalv4dnrtcx6s" }, "type": "object", "required": [ "id", "field_name" ], "properties": { "id": { "type": "string", "x-stoplight": { "id": "683fzmeuuhk30" } }, "field_name": { "type": "string", "x-stoplight": { "id": "xmw64vzyw9hzs" } }, "interval": { "type": "integer", "x-stoplight": { "id": "9k2hrurm3tc5e" } }, "max_buckets": { "type": "integer", "x-stoplight": { "id": "ql4lbd9xz662l" }, "default": 25, "minimum": 1, "maximum": 50 } } }, "AggResponse": { "title": "AggResponse", "x-stoplight": { "id": "1tf5rcv5w1xa5" }, "type": "object", "required": [ "id", "field", "buckets", "other" ], "properties": { "id": { "type": "string", "x-stoplight": { "id": "lh4hq6owyrxwh" } }, "field": { "type": "string", "x-stoplight": { "id": "ddb4r7m0feap5" } }, "buckets": { "type": "array", "x-stoplight": { "id": "scmbqt1envtze" }, "items": { "x-stoplight": { "id": "50br8c300e3i7" }, "type": "object", "required": [ "value", "count" ], "properties": { "value": { "type": "string", "x-stoplight": { "id": "1ok02j5jcab6z" } }, "count": { "type": "number", "x-stoplight": { "id": "iuojmof58ylzp" } } } } }, "other": { "type": "number", "x-stoplight": { "id": "bam2k0hwa9cux" }, "nullable": true } } }, "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" } } } }, "SearchReportRequest": { "title": "SearchReportRequest", "x-stoplight": { "id": "ut6cwssve0ncj" }, "type": "object", "properties": { "name": { "x-stoplight": { "id": "xwmrm9u79ppi5" }, "enum": [ "arrivals_departures", "demographics", "tenure", "tenure_distribution", "stats" ] }, "params": { "x-stoplight": { "id": "ruehjblj7z8rg" }, "oneOf": [ { "$ref": "#/components/schemas/ReportDemographicsParams" }, { "$ref": "#/components/schemas/ReportTenureParams" }, { "$ref": "#/components/schemas/ReportArrDepParams" }, { "$ref": "#/components/schemas/ReportStatsParams" } ] } } }, "ReportTenureParams": { "title": "ReportTenureParams", "x-stoplight": { "id": "qcf8fxvyuu4s0" }, "type": "object", "properties": { "date_from": { "type": "string", "x-stoplight": { "id": "7hpp97zucggn9" } }, "date_to": { "type": "string", "x-stoplight": { "id": "ux025vfa3ukvj" } }, "group_by": { "type": "array", "x-stoplight": { "id": "gnyvwn642okfk" }, "items": { "x-stoplight": { "id": "clk7o9qkrdyby" }, "type": "string" } }, "status": { "x-stoplight": { "id": "qfmouzosydyul" }, "enum": [ "active", "departed" ] }, "aggregate_type": { "x-stoplight": { "id": "fqow1zv0xw0hj" }, "enum": [ "monthly", "range" ] } } }, "ReportDemographicsParams": { "title": "ReportDemographicsParams", "x-stoplight": { "id": "sh5as9txnv8vn" }, "type": "object", "properties": { "date_from": { "type": "string", "x-stoplight": { "id": "adfen5arb0eg1" } }, "date_to": { "type": "string", "x-stoplight": { "id": "9twunts44w4dz" } }, "group_by": { "type": "array", "x-stoplight": { "id": "mqpnf3f3ttbu8" }, "items": { "x-stoplight": { "id": "2xrng7uab8hue" }, "type": "string" } }, "aggregate_type": { "x-stoplight": { "id": "l5dygqzekel8e" }, "enum": [ "monthly", "range" ] }, "status": { "x-stoplight": { "id": "h57v3hn4wwytr" }, "enum": [ "active", "departed" ] } } }, "ReportStatsParams": { "title": "ReportStatsParams", "x-stoplight": { "id": "go34bjoyr9xib" }, "type": "object", "properties": { "current_date": { "type": "string", "x-stoplight": { "id": "3mhz12ss02a5t" } } } }, "ReportArrDepParams": { "title": "ReportArrDepParams", "x-stoplight": { "id": "8txhuhjk9u5nu" }, "type": "object", "properties": { "date_from": { "type": "string", "x-stoplight": { "id": "mwpzrjm03m6vq" } }, "date_to": { "type": "string", "x-stoplight": { "id": "4kr72h808k1z1" } }, "group_by": { "type": "array", "x-stoplight": { "id": "7lyo8nw8nletf" }, "items": { "x-stoplight": { "id": "0oblf2kl5dco1" }, "type": "string" } } } } }, "requestBodies": { "PersonSearchBody": { "content": { "application/json": { "schema": { "type": "object", "x-stoplight": { "id": "zooad644t76el" }, "properties": { "filters": { "type": "array", "items": { "$ref": "#/components/schemas/FilterGroup" } }, "return_fields": { "type": "array", "description": "List of field names to return. For nested JSON fields, use dot notation (i.e. jobs.company.name)", "items": { "type": "string" } }, "past_jobs": { "type": "integer", "description": "How many previous jobs to include in the data" }, "size": { "type": "integer", "description": "The number of records to return in each page of the search. Defaults to 10. " }, "pagination_token": { "type": "string", "description": "If provided, returns the next page of data based on the `pagination_token`. \r\n\r\nThe `pagination_token` is only valid for a given set of filters/size -- the same `filters` and `size` must be supplied for every call using the `pagination_token` from a response with those filters. If the filters/size don't match the pagination_token, this call will return a `400`." }, "sort_by": { "type": "string", "description": "Which field to sort on. Use the pattern +name to sort ascending and -name to sort descending." }, "aggs": { "type": "array", "x-stoplight": { "id": "f2ebw2nh44kd2" }, "items": { "$ref": "#/components/schemas/AggRequest" } }, "report": { "$ref": "#/components/schemas/SearchReportRequest" } } } } }, "description": "" } } } } ```