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 against the NinjaHire dataset (Elastic). Same request and response shape as v2 person search; supports scroll_token for pagination.
Configuration: Requires NINJAHIRE_DATASET_BASE_URL, NINJAHIRE_DATASET_AUTH_USERNAME, and NINJAHIRE_DATASET_AUTH_PASSWORD. Returns 503 if not configured.
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
V2: Search for people
Search for people. Same request and response shape as v1 Person Search; supports scroll_token for pagination.
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
V2: Search for people (page-based)
Search for people with page-based pagination. Same query and sort as v2 search; use page (1-based) and size. No scroll_token required. Response includes data, total, page, size, and total_pages (when total is available).
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. Same as PersonSearchRequest query.
sizeinteger · min: 1 · max: 100Number of results per page (1-100)
Default: 10pageinteger · min: 1Page number (1-based)
Default: 1sortobject[]Sort specifications. Defaults to relevance (_score desc).
Default: [{"_score":"desc"}]
Responses
Search results returned successfully
dataobject[]Array of person records
totalintegerTotal number of matching results
pageintegerCurrent page number (1-based)
sizeintegerPage size (results per page)
total_pagesintegerTotal number of pages, computed as ceil(total / size) when
totalis present
V2 Sandbox: Search for people
Sandbox variant of V2 person search. Same request and response shape as /v2/person/search; supports scroll_token for pagination.
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
V2 Sandbox: Search for people (page-based)
Sandbox variant of V2 page-based person search. Same request and response shape as /v2/person/search/page; use page and size. Response includes total_pages when total is available.
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. Same as PersonSearchRequest query.
sizeinteger · min: 1 · max: 100Number of results per page (1-100)
Default: 10pageinteger · min: 1Page number (1-based)
Default: 1sortobject[]Sort specifications. Defaults to relevance (_score desc).
Default: [{"_score":"desc"}]
Responses
Search results returned successfully
dataobject[]Array of person records
totalintegerTotal number of matching results
pageintegerCurrent page number (1-based)
sizeintegerPage size (results per page)
total_pagesintegerTotal number of pages, computed as ceil(total / size) when
totalis present
V2: Search for people and enrich results
Search for people and enrich each result. Same request and response shape as v1 search-enrich; supports scroll_token for pagination.
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
V2: Get person schema mapping
Returns the raw Elastic mapping from GET /person/_mapping for the V2 person index.
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.
Responses
Search for people and enrich results
Same as Person Search: Elasticsearch search against the NinjaHire dataset, then 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).
Configuration: Requires Elastic dataset env vars and PDL_API_KEY. Returns 503 if Elastic or PDL is not configured.
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
V2: Enrich an individual person profile
Enrich an individual person profile.
In v2, use ninjagraph_id.
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
ninjagraph_idstringNinjaGraph 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
V2: Enrich person and return enriched profile with additional info
Enrich a person profile and return enriched data with additional profile fields.
Use ninjagraph_id in v2 requests.
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
ninjagraph_idstringNinjaGraph 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
V2: Bulk enrich person profiles with additional info
Bulk enrich person profiles and return enriched data with additional profile fields.
Use ninjagraph_id in each request item.
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
requestsobject[] · minItems: 1 · maxItems: 100 · requiredArray of enrich request objects.
Responses
Bulk data enriched successfully
dataobject[]Array of enriched response items in request order.
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 v2: Enrich person and return additional info
Sandbox enrich-info endpoint for person data.
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
ninjagraph_idstringNinjaGraph 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: 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