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
creditsobjectCredits for this request: what it cost and the balance after it. Present when the gateway charges credits for your account.
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.
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
V3: Search for people
Search for people. Same request and response shape as /v2/person/search. Requests scoped exclusively to India or the United States (via location_country) are answered from the NinjaHire dataset; every other request (other countries, a mix of countries, or no country filter) is answered from NinjaHire's global data network.
Authentication: All requests require an API key. Provide it either in the Authorization header as Bearer YOUR_KEY or in 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.
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. Requests scoped only to
location_countryof India or United States are served from the NinjaHire dataset; all others are served from NinjaHire's global data network.
sizeinteger · min: 1 · max: 25Number of results to return (1-25). Values above 25 are capped at 25.
Default: 10scroll_tokenstringToken for paginating through large result sets. Omit on the first request; pass the
scroll_tokenreturned in the previous response to fetch the next page. Keep the query's country scope unchanged across calls so the token stays valid.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
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 presentcreditsobjectCredits for this request: what it cost and the balance after it. Present when the gateway charges credits for your account.
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
creditsobjectCredits for this request: what it cost and the balance after it. Present when the gateway charges credits for your account.
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.
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
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
creditsobjectCredits for this request: what it cost and the balance after it. Present when the gateway charges credits for your account.
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.
creditsobjectCredits for this request: what it cost and the balance after it. Present when the gateway charges credits for your account.
V2: Waterfall enrich a person (email & mobile phone)
Find a person's personal email and mobile phone and receive their full profile on your callback URL.
NinjaHire runs a waterfall across multiple contact-data sources: previously enriched contacts are checked first, then each source is queried in turn until a personal email or mobile phone is found. The search stops at the first hit, so you only pay for the lookup that succeeded. Found contacts are merged into the person's NinjaGraph profile.
Matching inputs — send at least one strong identifier in person:
ninjagraph_id(if set, every otherpersonfield is ignored)linkedin_url/profile(most reliable — any LinkedIn URL form is accepted)email,email_hash,phoneorlid- or a name plus
company,schoolor a location field (a name alone is rejected)
The more context you add, the better the match. Unknown keys inside person are rejected with 400.
Callback — callback_url is required. When the waterfall finishes, the result is POSTed to your URL and this call returns 202 with the enrichment_id. A lookup can take up to a couple of minutes, so use a client timeout of at least 300 seconds. Any extra top-level keys you send (e.g. search_id, job_id) are echoed back in the callback params.
Callback body (found):
Code
Callback body (not found):
Code
Authentication: All requests require the X-API-Key header. Your tenant / consumer is resolved from the API key — do not send tenant_id in the body.
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
callback_urlstring · uri · requiredRequired. The result (profile or
NOT_FOUND) is POSTed here when the waterfall finishes.personobject · requiredThe person to enrich. All fields are optional strings, but at least one identifier (or a name plus company / school / location) is required.
Responses
Enrichment finished and the result was POSTed to callback_url (found or NOT_FOUND)
acceptedbooleanmessagestringenrichment_idstring · uuidcreditsobjectCredits for this request: what it cost and the balance after it. Present when the gateway charges credits for your account.
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
V2: Count people
Returns the number of people matching an Elasticsearch query (via Elasticsearch _count).
Headers
Authorizationstring · requiredThe
Authorizationheader is used to authenticate with the API using your API key. Value is of the formatBearer YOUR_KEY_HERE.
Responses
Count of matching people
countintegerNumber of people matching the query
creditsobjectCredits for this request: what it cost and the balance after it. Present when the gateway charges credits for your account. Same fields as
creditson the search and enrich responses.
V2: Preview search
Preview-tier person search: identity, current role/company/location and industry.
Headers
Authorizationstring · requiredThe
Authorizationheader is used to authenticate with the API using your API key. Value is of the formatBearer YOUR_KEY_HERE.
Responses
Preview-tier results
dataobject[]scroll_tokenstringcreditsobjectCredits for this request: what it cost (per person returned) and the balance after it. Present when the gateway charges credits for your account. Same fields as
creditson the search and enrich responses.
V2: Partial search
Partial person search: Preview fields plus employment history, skills, education and inferred years of experience.
Headers
Authorizationstring · requiredThe
Authorizationheader is used to authenticate with the API using your API key. Value is of the formatBearer YOUR_KEY_HERE.
Responses
Partial results
dataobject[]scroll_tokenstringcreditsobjectCredits for this request: what it cost (per person returned) and the balance after it. Present when the gateway charges credits for your account. Same fields as
creditson the search and enrich responses.