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

SignalHire’s database contains detailed professional profiles for hundreds of millions of people worldwide. The Person API allows looking up individuals using known identifiers — a LinkedIn profile URL, email address, phone number, or SignalHire profile UID — and retrieving their full profile data including contact information. Up to 100 identifiers can be submitted in a single request, and identifier types can be mixed freely within the same batch.
This endpoint consumes standard SignalHire credits for each successfully matched profile. Credits are shared across the website, browser extension, and API. See API Pricing for details.
The API works in two modes:
  • Async mode (default) — submit a request with a callbackUrl, receive a requestId immediately, and get results POSTed to your URL once ready. Suitable when maximum contact coverage is needed.
  • Sync mode (Without Waterfall) — submit a request without a callbackUrl and receive results immediately in the response. Faster, but may return fewer or slightly older contacts. See Without Waterfall mode.

​
Before You Start

Make sure you have:
Endpoint: POST https://www.signalhire.com/api/v1/candidate/search

​
Request Parameters

In Request Headers
​
apikey
string
required
Your secret API key. See Authentication.
In Request Body
​
items
array
required
Array of identifiers to look up. Each item can be a LinkedIn profile URL, email address, phone number, or 32-character SignalHire profile UID. Maximum 100 items per request. Types can be mixed freely within a single request.
​
callbackUrl
string
URL on your server where results will be POSTed once processing is complete. Required unless using withoutWaterfall. See Callback Delivery.
​
withoutWaterfall
boolean
If true, returns results synchronously in the response body instead of via callback. Cannot be combined with callbackUrl. See Without Waterfall mode.
​
withoutContacts
boolean
If true, returns profile data without contact details (emails, phones). Requires a separate credit type. See Without Contacts.

​
How It Works (Async Mode)

  1. Submit a POST request with an items array and a callbackUrl
  2. SignalHire immediately returns a requestId with HTTP 201
  3. The server queries internal and external sources for each item in parallel
  4. Once complete, results are POSTed to the callbackUrl
For a simpler synchronous flow without setting up a callback server, use Without Waterfall mode.

​
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/profile1",
"email@example.com",
"+44 0 123 456 789",
"10000000000000000000000000000001"
],
"callbackUrl": "https://www.yourdomain.com/yourCallbackUrl"
}'

​
Initial Response (HTTP 201)

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

{
  "requestId": 1748
}
HTTP 201 means the request was accepted and processing has started. The requestId uniquely identifies this request — it will be included in the Request-Id header of the callback payload, allowing incoming results to be matched to the original request. For other possible response codes — such as 401, 402, 429 — see Response Codes.

​
Callback Format

Once processing is complete, SignalHire POSTs an array to your callbackUrl. Each element corresponds to one item from the request and contains:
  • item — the original identifier submitted (LinkedIn URL, email, phone, or UID)
  • status — result of processing for this item (see status values below)
  • candidate — full profile object, present only when status is success. See Candidate Object for a complete field reference.
[
  {
    "item": "https://www.linkedin.com/in/profile1",
    "status": "success",
    "candidate": { "fullName": "Profile1", "contacts": [...], ... }
  },
  {
    "item": "email@email.com",
    "status": "failed"
  },
  {
    "item": "+44 0 808 189 3171",
    "status": "success",
    "candidate": { "fullName": "Profile2", ... }
  },
  {
    "item": "10000000000000000000000000000001",
    "status": "credits_are_over"
  }
]

​
Callback Status Values

StatusDescription
successProfile found and returned in the candidate field.
failedItem not found or could not be processed.
credits_are_overRan out of credits while processing this item.
timeout_exceededProcessing timed out (10-second limit).
duplicate_querySame request was submitted again within a short period.

​
Callback Delivery

Setting up a reliable callback endpoint is the responsibility of the API client. The endpoint must be publicly accessible, accept POST requests, and respond with HTTP 200 within 10 seconds. SignalHire has no way to re-initiate processing — if a callback is lost, a new API request must be submitted. Delivery flow:
  • Delivery is considered successful when the callback endpoint responds with HTTP 200
  • If the connection fails or times out (10 seconds), SignalHire retries 3 times sequentially
  • If all retries fail, the callback is discarded and the results are lost
  • The Request-Id header in the callback payload contains the original request ID for tracking
The callback endpoint must be publicly accessible and respond within 10 seconds. Heavy processing should not be performed inside the callback handler — acknowledge with 200 immediately and process the data asynchronously.
Delivery timing: Callback delivery time varies per request because SignalHire queries external APIs in real time to enrich contact data. Most requests complete within a few seconds, though some may take 30–60 seconds or more depending on external API response times. There is no fixed maximum — the callback is always sent once processing completes, regardless of how long it takes. There is no server-side timeout that would cause a callback to be silently dropped.

​
Failed Delivery Notifications

If callbacks could not be delivered, SignalHire sends an email notification once per hour listing the affected request IDs and error details. Example: 
We weren't able to deliver 2 responses to your callback URL due to the
network error on your end.

  cURL error 28: Operation timed out after 10001 milliseconds with 0 out
  of -1 bytes received.

Kindly check the request IDs below and make the required adjustments.

  132725817  132725819

You need to initiate new API calls to receive these responses.
Upon receiving such a notification, the issue with the callback endpoint should be resolved and new API requests submitted for the listed request IDs.

​
Rate Limits

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