Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.signalhire.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Search API allows searching SignalHire’s database of professionals using a wide variety of filters — job title, location, company, industry, experience, and more. Unlike the Person API, it does not require a known identifier. Results are returned as brief profile overviews without contact details, making it ideal for discovering new candidates or leads at scale. Results are returned synchronously — the first batch is included directly in the response. For large result sets, subsequent batches are retrieved using a scroll mechanism similar to Elasticsearch: each response includes a scrollId that can be passed to the Scroll Search endpoint to fetch the next batch. A typical workflow:
  1. Submit a searchByQuery request with filters — receive the first batch and a scrollId
  2. Use Scroll Search with the scrollId to page through remaining results
  3. Pass interesting profile UIDs to the Person API to retrieve full contact details
Maximum 3 concurrent Search API requests are allowed at a time.
Endpoint: POST https://www.signalhire.com/api/v1/candidate/searchByQuery

​
Request Parameters

Header
​
apikey
string
required
Secret API key. See Authentication.
Body
​
currentTitle
string
Boolean query for current job title. Cannot be combined with currentPastTitle — if both are provided, currentPastTitle takes precedence. See Boolean Query Guide.
​
currentPastTitle
string
Boolean query for current or past job title. Takes precedence over currentTitle if both are provided.
​
location
string | array of strings
Geographical area for the search. Accepts a single city, state, or country as a string, or multiple locations as an array. Examples: "Los Angeles, California", ["India", "Rome, Italy"]. Returns 422 if the location cannot be recognized.
​
latitude
float
Latitude coordinate for geo-based search. Must be provided together with longitude. Searches within a 10km radius. Overrides location when set.
​
longitude
float
Longitude coordinate for geo-based search. Must be provided together with latitude.
​
coordinates
array of objects
Multiple geographic points to search around simultaneously. Each item must contain latitude and longitude. Overrides location. Used only when top-level latitude/longitude are not set. Each point uses a 10km radius.
"coordinates": [
{ "latitude": 41.9028, "longitude": 12.4964 },
{ "latitude": 45.4642, "longitude": 9.1900 }
]
​
currentCompany
string
Boolean query for current company name.
​
currentPastCompany
string
Boolean query for current or past company name.
​
fullName
string
Search by full name.
​
keywords
string
Boolean query for skills, description, education, and other profile attributes.
​
industry
string
Filter by industry category. Returns 422 if the value is not recognized. See the full list of allowed values.
​
industries
array of strings
Filter by multiple industry categories simultaneously. Each value must be a valid industry name from the allowed values list. Returns 422 if any value is not recognized. Use instead of industry when filtering by more than one industry.
​
yearsOfCurrentExperienceFrom
integer
Minimum years of experience in the current role and company.
​
yearsOfCurrentExperienceTo
integer
Maximum years of experience in the current role and company.
​
yearsOfCurrentPastExperienceFrom
integer
Minimum years of experience across all roles and companies.
​
yearsOfCurrentPastExperienceTo
integer
Maximum years of experience across all roles and companies.
​
openToWork
boolean
Filter by open-to-work status.
​
excludeRevealed
boolean
Exclude profiles for which contacts have already been fetched.
​
excludeWatched
boolean
Exclude profiles already viewed in the web app or browser extension.
​
excludeInLists
boolean
Exclude profiles already added to a list.
​
excludeInProgress
boolean
Exclude profiles already added to a job.
​
excludeEmailed
boolean
Exclude profiles already emailed.
​
size
integer
Number of profiles to return per batch. Default: 10, must be between 1 and 100. Returns 422 if outside this range.
At least one non-exclude filter must be provided — an empty request returns 422. Exclude filters (excludeRevealed, excludeWatched, etc.) cannot be used as the only filters.

​
Location Formats

The location filter supports three levels of granularity. The value is resolved in this order: Country — pass the full English country name. Searches the entire country. 
"location": "Germany"
"location": ["India", "Brazil"]
State or Province — supported for the United States and Canada. The country suffix is optional. 
"location": "California"
"location": "California, United States"
"location": "Ontario, Canada"
City — pass a city name with enough context to identify it unambiguously. Searches within a 10km radius of the city center. 
"location": "Miami, Florida"
"location": "London, United Kingdom"
"location": "Berlin, Germany"
If the value cannot be resolved to any known location, the request returns HTTP 422 with "Location is not recognized". For precise geo-based search, use latitude/longitude or coordinates instead — they bypass text resolution entirely.

​
Request Example

This example searches for profiles in New York whose current job title contains “Software Engineer” or “Developer”, and who have both PHP and JavaScript mentioned in their profile. 
curl -X POST https://www.signalhire.com/api/v1/candidate/searchByQuery \
-H 'apikey: your_secret_api_key' \
--data '{
"currentTitle": "(Software AND Engineer) OR Developer",
"location": "New York, New York, United States",
"keywords": "PHP AND JavaScript"
}'

​
Response Example (HTTP 200)

HTTP/2 200
Content-Type: application/json
X-Credits-Left: 243

{
    "requestId": 3,
    "total": 12,
    "scrollId": "abc123",
    "profiles": [
    {
        "uid": "10000000000000000000000000001006",
        "fullName": "Aaron Smith",
        "location": "London, United Kingdom",
        "experience": [
            { "company": "Saward Dawson", "title": "Accountant" }
        ],
        "skills": ["Accounting", "Analysis"],
        "contactsFetched": null,
        "openToWork": false
    }
]
}

​
Response Fields

FieldDescription
requestIdID of this search. Required for Scroll Search.
totalTotal matching profiles across all pages.
profilesFirst batch of results. See Search Profile Object for field reference.
scrollIdPresent when total > size. Pass to Scroll Search to fetch the next batch. Expires in 15 seconds.
For other possible response codes see Response Codes.

​
Search Quota

Search requests are not billed per credit — they count against a daily search quota. This quota is shared between the SignalHire website and the API, so searches made in either place consume from the same daily limit. The daily quota covers two dimensions independently: the number of search queries and the total number of profiles returned across all searches. Both are tracked separately and either can be exhausted first depending on usage patterns. When the daily quota is exhausted, further search requests return HTTP 402 with an error message. The quota resets daily. There is also a concurrency limit: a maximum of 3 Search API requests can be in progress at the same time. Exceeding this returns HTTP 429.