--- updatedAt: 2025-03-26T16:58:25.000Z agentTools: projectIndex: https://docs.livedatatech.com/llms.txt --- # Preview searching for collections of people Get a preview of 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/preview": { "post": { "summary": "Preview searching for collections of people", "operationId": "search-persons-data-preview", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "people": { "type": "array", "description": "An array of all the matching people based on the provided filters and size.", "items": { "$ref": "#/components/schemas/SamplePerson" } }, "count": { "type": "integer" }, "aggs": { "x-stoplight": { "id": "dz39z5bctu110" }, "type": "array", "items": { "$ref": "#/components/schemas/AggResponse" } } } }, "examples": { "Example 1": { "value": { "people": [ { "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", "ended_at": "string", "location": "string", "company": { "id": "string", "name": "string", "linkedin": "string", "domain": "string" }, "is_first_at_company": true, "is_last_at_company": true }, "jobs": [ { "title": "string", "level": "C-Team", "function": "Banking and Wealth Management", "started_at": "string", "ended_at": "string", "location": "string", "company": { "id": "string", "name": "string", "linkedin": "string", "domain": "string" }, "is_first_at_company": true, "is_last_at_company": true } ], "education": [ { "school": "string" } ], "first_name": "string", "connections": 0, "employment_status": "employed" } ], "count": 0 } } } } } } }, "tags": [ "Search" ], "description": "Get a preview of people in Live Data that match the specified filters. ", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "x-stoplight": { "id": "ewv0y7puolts9" }, "properties": { "filters": { "type": "array", "items": { "$ref": "#/components/schemas/FilterGroup" } }, "sort_by": { "type": "string", "x-stoplight": { "id": "9wa7bj2v9ce0a" }, "description": "Which field to sort on. Use the pattern +name to sort ascending and -name to sort descending." }, "aggs": { "type": "array", "x-stoplight": { "id": "9s7ualfyabu0n" }, "items": { "$ref": "#/components/schemas/AggRequest" } } } } } } }, "x-stoplight": { "id": "b94qf8fttotpp" } }, "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" } } }, "SamplePerson": { "title": "SamplePerson", "x-stoplight": { "id": "a4arz18yeuv0h" }, "type": "object", "description": "Represents a sample of the Person object, used for previewing data.", "properties": { "id": { "type": "string", "description": "The unique Live Data ID for this person" }, "created_at": { "type": "string", "description": "Date the person was added to Live Data" }, "info_change_detected_at": { "type": "string", "description": "Most recent date that any field changed." }, "title_change_detected_at": { "type": "string", "description": "Most recent date that Live Data detected a title change." }, "company_change_detected_at": { "type": "string", "description": "Most recent date that Live Data detected a company change." }, "position": { "$ref": "#/components/schemas/SampleJob" }, "jobs": { "type": "array", "items": { "$ref": "#/components/schemas/SampleJob" } }, "education": { "type": "array", "description": "Array of the education history for this person", "items": { "type": "object", "properties": { "school": { "type": "string", "description": "Name of the school" } } } }, "first_name": { "type": "string", "description": "First name, if known" }, "connections": { "type": "integer", "description": "Number of connections on LinkedIn" }, "employment_status": { "enum": [ "employed", "unemployed", "retired" ] } } }, "SampleJob": { "title": "SampleJob", "x-stoplight": { "id": "3c70z9b5fyhl2" }, "type": "object", "description": "Represents a job, which is a combination of Company+Title", "properties": { "title": { "type": "string", "description": "Title of the person at this job" }, "level": { "description": "Level derived from title using internal ML process", "enum": [ "C-Team", "VP", "Director", "Manager", "Staff", "Senior Staff", "Intern", "Consultant" ] }, "function": { "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", "description": "Date the person started this job. Will always be the 1st day of a month at 00:00" }, "ended_at": { "type": "string", "description": "Date this job ended. Will always be the 1st day of a month at 00:00" }, "location": { "type": "string", "description": "Location of this job" }, "company": { "$ref": "#/components/schemas/SampleCompany" }, "is_first_at_company": { "type": "boolean", "description": "Boolean value to indicate whether this is the person’s first job at this company" }, "is_last_at_company": { "type": "boolean", "description": "Boolean value to indicate whether this is the person’s last job at this company. Note this will be `true` for active jobs." } } }, "SampleCompany": { "title": "SampleCompany", "x-stoplight": { "id": "cfaqom1koly07" }, "type": "object", "description": "Dict of company-specific information related to the job", "properties": { "id": { "type": "string", "description": "Unique Live Data ID for this company" }, "name": { "type": "string", "description": "Name of the company" }, "linkedin": { "type": "string", "description": "LinkedIn slug for the company" }, "domain": { "type": "string", "description": "Primary domain for the company" } } }, "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 } } }, "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" } } } } } } } ```