Reverse Contact Reverse Contact
Sign Up

People search

14 min read

Search the database for people with filters and get full profiles back with cursor pagination.

POST
Sign up to try

Introduction

The People Search endpoint returns full person profiles matching a combination of filters. All filters are optional and combined with AND logic. Results are drawn from our cache-based search index. This endpoint never triggers a live fetch.

Every result is a complete profile, the same shape the Profile endpoint returns, so you do not need a second call to get the full data of a hit. Use the free People search count endpoint to check how many profiles match before you spend credits.

Coming from POST /v2/search/persons? See Migrating people search from persons to people.

Authorization

apikey string required
Your API key from the developer dashboard. Pass it via Authorization: Bearer YOUR_API_KEY header.

Request body

All filters are optional and combined with AND logic. Scalar filters live in the table below; the nested-object filters (followersCount, currentCompanyEmployeeCountRange, totalExperienceMonths, location, experience) are documented as expandable field items right after, and pagination (cursor, perPage) closes the section.

firstName string
Filter by first name
lastName string
Filter by last name
headline string
Match keywords found in the profile headline
email string
Filter by email address
isOpenToWork boolean
Restrict to profiles flagged open-to-work
isCurrentlyEmployed boolean
Restrict to profiles that have a current employer
isPremium boolean
Restrict to Social Premium members
isVerified boolean
Restrict to profiles with a verification badge
currentPositionTitle string | string[]
Current position title, or array of titles: a person matches if their current title matches any of them
excludeCurrentPositionTitle string | string[]
Current position title, or array of titles, to exclude from results
positionTitle string | string[]
Current or past position title, or array of titles (OR-matched)
excludePositionTitle string | string[]
Current or past position title, or array of titles, to exclude
currentCompanyName string
Match the current employer name
excludeCurrentCompanyName string
Exclude the current employer name
companyName string | string[]
Current or past company name, or array of names (OR-matched)
excludeCompanyName string | string[]
Current or past company name, or array of names, to exclude
currentCompanyId string | string[]
ReverseContact internal id (com_...) of the current employer
excludeCurrentCompanyId string | string[]
Current employer com_... id, or array of ids, to exclude
companyId string | string[]
Current or past company com_... id, or array of ids
excludeCompanyId string | string[]
Current or past company com_... id, or array of ids, to exclude
currentCompanyLinkedinId string | string[]
Current employer Social identifier, or array of identifiers
excludeCurrentCompanyLinkedinId string | string[]
Current employer Social identifier, or array, to exclude
companyLinkedinId string | string[]
Current or past company Social identifier, or array of identifiers
excludeCompanyLinkedinId string | string[]
Current or past company Social identifier, or array, to exclude
currentCompanyPublicId string | string[]
Current employer public ID or slug, or array
excludeCurrentCompanyPublicId string | string[]
Current employer public ID or slug, or array, to exclude
companyPublicId string | string[]
Current or past company public ID or slug, or array
excludeCompanyPublicId string | string[]
Current or past company public ID or slug, or array, to exclude
currentCompanyIndustry string | string[]
Current employer industry. See Industry values for the full list
companyIndustry string | string[]
Current or past company industry, from the same industry list
excludeCompanyIndustry string | string[]
Current or past company industry, or array, to exclude
currentFunction string | string[]
Current function from the position taxonomy
excludeCurrentFunction string | string[]
Current function, or array of functions, to exclude
currentSubFunction string | string[]
Current sub-function from the position taxonomy
excludeCurrentSubFunction string | string[]
Current sub-function, or array of sub-functions, to exclude
currentSeniority string | string[]
Current seniority from the position taxonomy
excludeCurrentSeniority string | string[]
Current seniority, or array of seniorities, to exclude
maxDataAgeDate string
ISO 8601 datetime. Only returns profiles refreshed after this date
cursor string
Opaque cursor returned as metadata.nextCursor; request the next page
perPage number
Profiles per page (1 to 100, default 25)

Filter validation: filters are validated before the query runs. Unknown field names, blank values, values outside a closed list (currentCompanyIndustry, currentFunction, currentSubFunction, currentSeniority, location.countryCode) and inconsistent ranges return HTTP 422 with the offending field, the reason and suggested values, and cost 0 credits. Unknown fields are rejected rather than ignored, because an ignored filter would return unfiltered results. Each list filter accepts at most 20 values. See Search filter validation.

Note: Title matching is token-based, not exact: "CTO" also matches "Deputy CTO". Multiple titles are OR-matched, and exclusions always win over matches. The positionTitle, companyName, companyId, companyLinkedinId, companyPublicId and companyIndustry filters match current and past positions, while their current... counterparts match the current position only.

followersCountobject
Filter by follower count range. Both bounds are optional and inclusive.
Show child attributesHide child attributes
min number
Minimum value, inclusive
max number
Maximum value, inclusive
currentCompanyEmployeeCountRangeobject
Filter by the current company employee count range. Both bounds are optional and inclusive. Headcount is stored as fixed size brackets (1, 2-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5001-10000, 10001+), not as an exact number, and a range only matches a bracket it fully contains. Send bracket boundaries, otherwise the range contains no bracket, matches nothing and returns an empty data.data array.
Show child attributesHide child attributes
min number
Lower bound, inclusive. Must be a bracket start: 1, 2, 11, 51, 201, 501, 1001, 5001, 10001
max number
Upper bound, inclusive. Must be a bracket end: 1, 10, 50, 200, 500, 1000, 5000, 10000. Omit it to include 10001+

Examples: { "min": 11, "max": 50 } matches the 11-50 bracket. { "min": 11, "max": 200 } spans 11-50 and 51-200. { "min": 10001 } matches 10001+. { "min": 11, "max": 20 } returns an empty array, because no whole bracket fits between 11 and 20.

totalExperienceMonthsobject
Filter by total career length in months. Both bounds are optional and inclusive, from 0 to 1200.
Show child attributesHide child attributes
min number
Minimum value, inclusive
max number
Maximum value, inclusive
locationobject
Multi-field location filter. Each sub-field is optional and accepts a single string or an array of strings (OR matching).
Show child attributesHide child attributes
country string | string[]
Country name (e.g. "France")
countryCode string | string[]
ISO 3166 country code (e.g. "FR")
region string | string[]
State or region
city string | string[]
City
area string | string[]
Broader geographic area
experienceobject[]
Required past experience. Each entry demands a position taxonomy value, with an optional minimum tenure. Entries are AND-combined, up to 10 per request.
Show child attributesHide child attributes
dimension string
Taxonomy dimension: function, subFunction or seniority
value string
Value from the selected dimension of the position taxonomy
minMonths number
Optional minimum tenure in that dimension, in months (0 to 720)

Position taxonomy

currentFunction, currentSubFunction, currentSeniority and the experience filter match a closed taxonomy of professional functions. A value must come from the taxonomy: case and surrounding spaces are ignored, and any other value is rejected with HTTP 422 and the closest valid values, never silently ignored.

There are 32 functions, 386 sub-functions and 10 seniorities. The functions and seniorities are listed below; the full sub-function list is long, so read it from the available fields endpoint, which returns every accepted value for each filter, plus the function each sub-function belongs to.

Functions (32)

  • Administrative
  • Agriculture and Environment
  • Construction and Trades
  • Consulting and Advisory
  • Customer Service
  • Design
  • Education
  • Energy and Utilities
  • Entertainment and Gaming
  • Executive and Leadership
  • Finance
  • Hospitality and Tourism
  • Human Resources
  • Legal
  • Marketing
  • Media and Communications
  • Medical and Health
  • Nonprofit and Government
  • Not Employed
  • Operations
  • Other
  • Personal and Home Services
  • Product
  • Project and Program Management
  • Public Safety and Security
  • Real Estate
  • Research and Science
  • Retail and Consumer
  • Sales
  • Software
  • Traditional Engineering
  • Transportation and Logistics

Seniorities (10)

  • CXO
  • VP
  • Director
  • Head
  • Manager
  • Partner
  • Owner / Founder
  • Individual Contributor
  • Intern
  • Other

Pagination and credits

People search uses cursor pagination. Each response returns up to perPage profiles (1 to 100, default 25) and a metadata.nextCursor value. Pass that value back as cursor in the next request to get the following page; nextCursor is null on the last page. The cursor is opaque: send it back unchanged, without parsing or altering it. There is no page parameter.

perPage above 100 returns HTTP 422 with error.code PAGINATION_LIMIT_EXCEEDED, and the error.details object identifies the field and maximum, for example { "field": "perPage", "max": 100 }.

People search costs 1 credit per profile delivered. Compliance-blocked profiles are removed before the response and are not billed. A page that returns 25 profiles costs 25 credits, and a page that returns no profile costs 0 credits. Check the size of a query first with the free People search count endpoint, and lower perPage to control how many credits a single request can spend.

Response structure

Note: This endpoint uses a nested envelope. The top-level V2 data field wraps an inner search payload that contains the actual results array (data.data) and the pagination info (data.metadata). See the example response for the exact shape.

success boolean
true if the request was processed successfully
error null
Always null on success
data.dataobject[]
Full profiles returned for this page, wrapped under data.data in the envelope. Empty array if no match. Each item is the same full profile shape as the Profile endpoint; the table below lists its main fields.
Show child attributesHide child attributes
id string
ReverseContact internal person identifier (prs_...)
publicId string
Social public identifier (the /in/xxx slug)
memberId string | null
Upstream member identifier when available
linkedinUrl string
Full Social profile URL
firstName string | null
First name
lastName string | null
Last name
headline string | null
Profile headline
summary string | null
Profile summary
isOpenToWork boolean
Whether the profile is flagged open to work
hasPremium boolean
Whether the profile has Social Premium
hasVerificationBadge boolean
Whether the profile has a verification badge
photoUrl string | null
Profile photo URL
creationDate string | null
When the profile was created (ISO 8601)
followersCount number | null
Follower count
connectionsCount number | null
Connection count
currentPosition object | null
Current job position (how it is chosen)
experience array
Professional experiences, same shape as currentPosition
education array
Education history
skills string[]
Skills listed on the profile
languages array
Spoken languages
certifications array
Professional certifications
recommendations array
Received recommendations
locationobject
Geographic location (null if unknown)
Show child attributesHide child attributes
city string | null
City
state string | null
State or region
country string | null
Country name
countryCode string | null
ISO country code (e.g. "US")
rawLocation string | null
Raw location string as displayed on the profile
currentPositionobject
Current job position (null if no current position)
Show child attributesHide child attributes
title string | null
Job title
description string | null
Position description
contractType string | null
Contract type
companyName string | null
Company name
companyLinkedinId string | null
Company Social identifier
companyUrl string | null
Company Social URL
companyLocation string | null
Company location
companyLogoUrl string | null
Company logo URL
startEndDate object | null
Period boundaries (DateRange)
data.metadataobject
Pagination metadata wrapped under data.metadata in the envelope.
Show child attributesHide child attributes
perPage number
Profiles requested per page
count number
Profiles returned in this page. Use People search count for the total matching set
nextCursor string | null
Opaque cursor for the next page, null on the last page
quotasobject
Credits and rate limit usage after this request
Show child attributesHide child attributes
creditsConsumed number
Credits consumed by this request
workspaceobject
Workspace-level limits
Show child attributesHide child attributes
id string
Your workspace identifier
hasUnlimitedCredits boolean
Whether workspace credits are unlimited
allowDailyOvercost boolean
Whether the workspace may exceed its daily cap
creditsobject
Credit balance
Show child attributesHide child attributes
total number
Total credits in your plan
used number
Credits consumed so far
left number
Remaining credits
dailyLimitobject
Daily request limit (null if not configured)
Show child attributesHide child attributes
limit number
Maximum requests per day
used number
Requests made today
left number
Remaining requests today
nextReset string
When the daily window resets (ISO 8601)
minuteRateLimitobject
Per-minute rate limit
Show child attributesHide child attributes
limit number
Maximum requests per minute
used number
Requests made in the current minute
left number
Remaining requests in the current minute
nextReset string
When the minute window resets (ISO 8601)
keyobject
API key-level limits (null when request is from dashboard)
Show child attributesHide child attributes
id string
API key identifier
dailyLimitobject
Daily limit for this key (null if not configured)
Show child attributesHide child attributes
limit number
Maximum requests per day
used number
Requests made today
left number
Remaining requests today
nextReset string
When the daily window resets (ISO 8601)
minuteRateLimitobject
Minute rate limit for this key
Show child attributesHide child attributes
limit number
Maximum requests per minute
used number
Requests made in the current minute
left number
Remaining requests in the current minute
nextReset string
When the minute window resets (ISO 8601)
metadataobject
Request tracking information (not to be confused with data.metadata which is pagination)
Show child attributesHide child attributes
requestId string
Unique identifier for this request
executionTimeMs number
Total execution time in milliseconds

Previous

Enrich company

Next

People search count

Related articles