NinjaHire People APIs enable searching and enriching professional person profiles with verified employment, education, contact, and social information. These endpoints provide access to person search using Elasticsearch query syntax and person enrichment with comprehensive profile data.
Search for people
Search for people using advanced Elasticsearch-style query syntax. This API allows precise discovery of professionals based on job title, company, location, skills, experience, and more.
Key Features:
- Advanced Elasticsearch query DSL
- Boolean, filter, match, range, and exists queries
- Sorting and pagination
- Scroll-based retrieval for large result sets
- Returns rich person profiles:
- Employment history
- Education
- Skills
- Social profiles
- Contact information (when available)
Authentication: All requests require ONLY the X-API-Key header with your API key. Do not use the Authorization header - it is not required for this endpoint.
Headers
Authorizationstring · requiredThe
Authorizationheader is used to authenticate with the API using your API key. Value is of the formatBearer YOUR_KEY_HERE.X-API-Keystring · requiredRequired. Your API key for authentication. This is the only authentication header needed for this endpoint. Do not use the Authorization header.
Request Body optional
queryobject · requiredRequired. Elasticsearch-style query DSL for searching. Supports bool queries with filter, must, must_not, and should clauses. Use terms, match, match_phrase, exists, range, and other Elasticsearch query types.
sizeinteger · min: 1 · max: 100Number of results to return (1-100)
Default: 10frominteger · min: 0Offset for pagination
Default: 0scroll_tokenstringToken for scrolling through large result sets
sortobject[]Array of sort specifications. Each item can specify a field and order (asc/desc). Defaults to sorting by relevance score (desc).
Default: [{"_score":"desc"}]
Responses
Search results returned successfully
statusintegerHTTP status code
totalintegerTotal number of matching results
scroll_tokenstringToken for pagination (if more results available)
dataobject[]Array of person records
Search for people and enrich results
Same as Person Search: same request body and query syntax. After fetching search results from People Data Labs, each result is bulk-enriched via PDL's person/bulk API. Response has the same shape as Person Search, with each item in data merged with its enriched profile (enrich data overlays search data).
Authentication: All requests require ONLY the X-API-Key header with your API key.
Headers
Authorizationstring · requiredThe
Authorizationheader is used to authenticate with the API using your API key. Value is of the formatBearer YOUR_KEY_HERE.X-API-Keystring · requiredRequired. Your API key for authentication.
Request Body optional
queryobject · requiredRequired. Elasticsearch-style query DSL for searching. Supports bool queries with filter, must, must_not, and should clauses. Use terms, match, match_phrase, exists, range, and other Elasticsearch query types.
sizeinteger · min: 1 · max: 100Number of results to return (1-100)
Default: 10frominteger · min: 0Offset for pagination
Default: 0scroll_tokenstringToken for scrolling through large result sets
sortobject[]Array of sort specifications. Each item can specify a field and order (asc/desc). Defaults to sorting by relevance score (desc).
Default: [{"_score":"desc"}]
Responses
Search results returned and enriched successfully
statusintegerHTTP status code
totalintegerTotal number of matching results
scroll_tokenstringToken for pagination (if more results available)
dataobject[]Array of person records
Enrich an individual person profile
Enrich an individual person profile.
Response: status, likelihood, data, dataset_version. See the response schema and example for the exact fields in data.
Authentication: All requests require ONLY the X-API-Key header with your API key. Do not use the Authorization header - it is not required for this endpoint.
Headers
Authorizationstring · requiredThe
Authorizationheader is used to authenticate with the API using your API key. Value is of the formatBearer YOUR_KEY_HERE.X-API-Keystring · requiredRequired. Your API key for authentication. This is the only authentication header needed for this endpoint. Do not use the Authorization header.
Request Body
pdl_idstringUnique person identifier
first_namestringFirst name of the person
last_namestringLast name of the person
middle_namestringMiddle name of the person
full_namestringFull name of the person
emailstringEmail address
phone_numberstringPhone number (E.164 format recommended)
job_titlestringJob title or role
company_namestringCompany name
locationstringLocation (city, state, country, etc.)
schoolstringSchool or university name
profilestring[]Array of social profile URLs (LinkedIn, Twitter, etc.)
min_likelihoodinteger · min: 1 · max: 10Minimum match threshold (1-10)
include_if_matchedbooleanReturn only if match found
Default: false
Responses
Data enriched successfully
statusintegerHTTP status code
likelihoodintegerMatch likelihood score (1-10)
dataEnriched person record, or null if no match found
dataset_versionstringDataset version identifier, if applicable
Sandbox: Search for people
Same as Person Search but uses PDL sandbox base URL (PDL_SANDBOX_BASE_URL). Request/response identical to /v1/person/search.
Authentication: All requests require the X-API-Key header.
Headers
Authorizationstring · requiredThe
Authorizationheader is used to authenticate with the API using your API key. Value is of the formatBearer YOUR_KEY_HERE.X-API-Keystring · requiredYour API key for authentication.
Request Body optional
queryobject · requiredRequired. Elasticsearch-style query DSL for searching. Supports bool queries with filter, must, must_not, and should clauses. Use terms, match, match_phrase, exists, range, and other Elasticsearch query types.
sizeinteger · min: 1 · max: 100Number of results to return (1-100)
Default: 10frominteger · min: 0Offset for pagination
Default: 0scroll_tokenstringToken for scrolling through large result sets
sortobject[]Array of sort specifications. Each item can specify a field and order (asc/desc). Defaults to sorting by relevance score (desc).
Default: [{"_score":"desc"}]
Responses
Search results returned successfully
statusintegerHTTP status code
totalintegerTotal number of matching results
scroll_tokenstringToken for pagination (if more results available)
dataobject[]Array of person records
Sandbox: Enrich an individual person profile
Same as Person Enrich but uses PDL sandbox base URL (PDL_SANDBOX_BASE_URL). Request/response identical to /v1/person/enrich.
Authentication: All requests require the X-API-Key header.
Headers
Authorizationstring · requiredThe
Authorizationheader is used to authenticate with the API using your API key. Value is of the formatBearer YOUR_KEY_HERE.X-API-Keystring · requiredYour API key for authentication.
Request Body
pdl_idstringUnique person identifier
first_namestringFirst name of the person
last_namestringLast name of the person
middle_namestringMiddle name of the person
full_namestringFull name of the person
emailstringEmail address
phone_numberstringPhone number (E.164 format recommended)
job_titlestringJob title or role
company_namestringCompany name
locationstringLocation (city, state, country, etc.)
schoolstringSchool or university name
profilestring[]Array of social profile URLs (LinkedIn, Twitter, etc.)
min_likelihoodinteger · min: 1 · max: 10Minimum match threshold (1-10)
include_if_matchedbooleanReturn only if match found
Default: false
Responses
Data enriched successfully
statusintegerHTTP status code
likelihoodintegerMatch likelihood score (1-10)
dataEnriched person record, or null if no match found
dataset_versionstringDataset version identifier, if applicable
Sandbox: Search for people and enrich results
Same as Person Search Enrich but uses PDL sandbox base URL (PDL_SANDBOX_BASE_URL). Request/response identical to /v1/person/search-enrich.
Authentication: All requests require the X-API-Key header.
Headers
Authorizationstring · requiredThe
Authorizationheader is used to authenticate with the API using your API key. Value is of the formatBearer YOUR_KEY_HERE.X-API-Keystring · requiredYour API key for authentication.
Request Body optional
queryobject · requiredRequired. Elasticsearch-style query DSL for searching. Supports bool queries with filter, must, must_not, and should clauses. Use terms, match, match_phrase, exists, range, and other Elasticsearch query types.
sizeinteger · min: 1 · max: 100Number of results to return (1-100)
Default: 10frominteger · min: 0Offset for pagination
Default: 0scroll_tokenstringToken for scrolling through large result sets
sortobject[]Array of sort specifications. Each item can specify a field and order (asc/desc). Defaults to sorting by relevance score (desc).
Default: [{"_score":"desc"}]
Responses
Search results returned and enriched successfully
statusintegerHTTP status code
totalintegerTotal number of matching results
scroll_tokenstringToken for pagination (if more results available)
dataobject[]Array of person records