Skip to main content
By default, the Person API is asynchronous — a request is submitted and results arrive via a callback URL. The withoutWaterfall mode changes this to a synchronous flow: results are returned immediately in the response body.

​
How It Differs

Standard (async)withoutWaterfall (sync)
Response timeSlower (queries external APIs)Fast, immediate
Requires callback serverYesNo
Callback UrlRequiredNot allowed
External API enrichmentYesNo — only internal data
Contact coverageHigherLower
Data freshnessHigherMay be less current
Without contacts modeSupportedSupported — combine with withoutContacts: true
Use withoutWaterfall when a fast response is needed and fewer or slightly older contacts are acceptable. Use the standard async mode when completeness matters more than speed.

​
Request Parameters

The same parameters apply as in the standard Retrieve Person Data endpoint, with two differences:
  • withoutWaterfall must be set to true
  • callbackUrl must not be included
Optionally, withoutContacts: true can be added to retrieve profiles without contact details synchronously. This uses without-contacts credits instead of standard credits.

​
Request Example

curl -X POST https://www.signalhire.com/api/v1/candidate/search \
-H 'apikey: your_secret_api_key' \
--data '{
"items": [
"https://www.linkedin.com/in/jennwolf",
"10000000000000000000000000001001",
"+123 45 6777"
],
"withoutWaterfall": true
}'
callbackUrl cannot be used together with withoutWaterfall. Including both will return HTTP 406.

​
Response Example (HTTP 200)

The response format is identical to the callback payload in standard mode — an array of result objects returned directly. Each element contains item, status, and candidate when successful. See Candidate Object for a complete field reference. 
HTTP/2 200
Content-Type: application/json
X-Credits-Left: 241

[
{
    "item": "https://www.linkedin.com/in/jennwolf",
    "status": "success",
    "candidate": { "fullName": "Jenn Wolf", "contacts": [...], ... }
},
{
    "item": "10000000000000000000000000001001",
    "status": "success",
    "candidate": { "fullName": "John Dou", "contacts": [...], ... }
},
{
    "item": "+123 45 6777",
    "status": "failed"
}
]
For other possible response codes — such as 401, 402, 406, 429 — see Response Codes.

​
Response Status Values

StatusDescription
successProfile found and returned in the candidate field.
failedItem not found or could not be processed.
credits_are_overCredits ran out while processing this item.
duplicate_querySame request was submitted again within a short period.

​
Rate Limits

For information on request limits and throttling, see Rate Limits.

​
When to Use withoutWaterfall

Use withoutWaterfall when:
  • A fast synchronous response is more important than maximum contact coverage
  • Setting up a publicly accessible callback server is not feasible — for example, in local development, scripts, or environments without a public endpoint.
Use standard async mode with callbackUrl when completeness matters more than speed — it queries external APIs in real time and returns the most up-to-date contact data available.