The SignalHire skill integrates the full SignalHire API into OpenClaw, enabling you to search for prospects and enrich their contact details without leaving your workflow. It exposes three core actions: a credits check, a search-by-query for prospecting, and an asynchronous contact enrichment call

Prospect and enrich contacts via the SignalHire API (Search, Person and Credits)

Security Scan

The skill’s behavior mostly matches a SignalHire integration, but there are inconsistencies (missing declared env vars in the registry, code files with no install instructions) and modest operational risks (webhook callback, model-autonomous invocation) that warrant caution.

Purpose & Capability

The name and description align with the SignalHire API (credits, search, person/enrichment). The SKILL.md explicitly requires SIGNALHIRE_API_KEY and SIGNALHIRE_CALLBACK_URL which are appropriate for the described async enrichment workflow. However, the registry metadata lists no required env vars/primary credential while SKILL.md declares them — that mismatch is an incoherence and should be corrected. The presence of connector code (connector/main.py) is coherent with the need for a callback/connector service, but the package provides no install spec or homepage, so it's unclear how that connector is expected to be deployed.

Instruction Scope

SKILL.md stays within the stated purpose: it documents how to check credits, perform search, and run Person API jobs with a required callback. It warns not to leak the API key and specifies rate/concurrency limits and expected callback semantics. It does not instruct the agent to read unrelated files or credentials.

Install Mechanism

There is no install spec (instruction-only), which is low-risk. However, code files (connector/main.py and __init__.py) are present in the bundle but there are no instructions on how/when these files are installed or executed. This is an implementation inconsistency: either the connector is expected to be run by the platform or the user, but that is not documented in the registry metadata or SKILL.md in an explicit install section.

Credentials

Requiring SIGNALHIRE_API_KEY and SIGNALHIRE_CALLBACK_URL is proportional to the stated purpose. The concern is the mismatch between the SKILL.md's declared required env vars and the registry metadata (which lists none). Also the callback URL must be publicly reachable—users must understand that the skill will instruct SignalHire to POST potentially sensitive contact data to that endpoint, so the callback endpoint should be under the user's control and secured.

Persistence & Privilege

The skill does not set always:true (good) but does not set disableModelInvocation:true, so the model can autonomously invoke the skill. That means an agent could start enrichment jobs (consuming account credits) and cause SignalHire to POST data to the supplied callback URL without an explicit user step. The connector is described as persisting results to CSV; where those files live and their access controls are not documented. Those operational privileges warrant explicit user controls (e.g., require user invocation, audit logs, or whitelist callback URLs).

What to consider before installing

Do not install until you confirm a few things: 1) Fix the registry metadata: the SKILL.md requires SIGNALHIRE_API_KEY and SIGNALHIRE_CALLBACK_URL but the registry lists none — ask the publisher to correct this. 2) Verify the connector code before running: request the connector/main.py source (it exists in the package) and review it locally or in an isolated environment to see what it writes to disk and what network endpoints it uses. 3) Provide a callback URL you control and secure it (HTTPS, IP/host restrictions, auth) because SignalHire will POST contact data there; expect PII in those payloads. 4) Decide whether you want the model to be able to invoke this skill autonomously; if not, ask the author to set disableModelInvocation:true or ensure user-invocable only. 5) Confirm where CSVs are stored, retention policies, and who can access them. 6) Prefer a published source/homepage and clearer install/run instructions before trusting the skill with your SignalHire API key or account credits.

SignalHire skill instructions

This skill exposes three high‑level capabilities to an OpenClaw agent. Each capability corresponds to one of the REST endpoints documented by SignalHire. The agent should never call these endpoints directly; instead it must invoke one of the defined skill actions. The following guidance summarises how the API works, including rate limits, concurrency limits and the asynchronous callback workflow. All factual statements below are supported by the official SignalHire API documentation.

1. Check remaining credits

Use this action to determine how many credits remain on the account. The SignalHire API exposes a dedicated endpoint GET /api/v1/credits which returns the number of available credits as a JSON payload. A valid API key must be included in the request headers. When invoked successfully, the response contains a field called credits with the number of credits remaining【821841938681143†L505-L529】. If the account is configured for “profiles without contacts”, the same endpoint can be called with a withoutContacts=true query parameter【821841938681143†L559-L566】. Credits are also returned in the X-Credits-Left response header for every Person API call【821841938681143†L559-L566】.

The agent must call this action before launching large enrichment jobs to avoid running out of credits mid‑operation. If the number of remaining credits is lower than the number of items to be enriched, the job should be split or aborted gracefully.

2. Search for profiles

Use this action to find prospective candidates in the SignalHire database without consuming contact credits. The Search API endpoint is POST /api/v1/candidate/searchByQuery【21055727237259†L100-L109】 and returns a list of profile summaries along with a scrollId. The scrollId can be used to fetch additional pages via the Scroll Search endpoint (not shown here) until all results are exhausted. Access to the Search API is granted only after contacting SignalHire support and is subject to a strict concurrency limit of three simultaneous requests【21055727237259†L110-L116】. The agent must ensure that no more than three searchByQuery calls are inflight at any time.

When performing a search, the request body should include fields such as currentTitle, location, keywords, industry and other filters as described in the documentation【21055727237259†L120-L177】. The size parameter controls how many profiles are returned per page (default 10, maximum 100). After retrieving the first page, the agent should immediately follow up with a scroll request within 15 seconds to avoid expiration of the scrollId. The response from search is synchronous and will return immediately; no callback is needed.

3. Enrich contacts (Person API)

This action retrieves full contact information (emails, phones and social profiles) for up to 100 items per request. The endpoint is POST /api/v1/candidate/search【821841938681143†L126-L134】. Each item may be a LinkedIn profile URL, an email address, a phone number or a SignalHire profile UID【821841938681143†L120-L124】. The request body must include a callbackUrl parameter; once the data is processed the API posts the results to this URL【821841938681143†L126-L134】. A valid server listening on the callbackUrl must return HTTP status 200 to acknowledge successful receipt. SignalHire retries up to three times if the callback endpoint cannot be reached or if it does not respond within a ten‑second timeout【821841938681143†L187-L198】. Processing is complete only when all callback payloads have been received.

The callback payload contains an array of objects, each with a status field indicating the outcome for that item: success, failed, credits_are_over, timeout_exceeded or duplicate_query【821841938681143†L239-L249】. When the status is success, the payload also includes a candidate object with fields such as fullName, emails, phones, location, etc. These results are persisted by the connector service into a CSV file; the agent should wait until the connector reports that the job is ready before consuming the data.

The Person API is subject to rate limits: a maximum of 600 elements processed per minute【821841938681143†L490-L503】. The agent must implement throttling to ensure that the combined number of items in all Person API calls does not exceed this limit. Requests exceeding the limit will be rejected with HTTP status 429 Too Many Requests【821841938681143†L500-L503】. To maximise throughput, batch up to 100 items per request but do not exceed the global per‑minute quota.

General guidance for agents

1. Do not hard‑code the API key or callback URL. Use the environment variables injected by OpenClaw: SIGNALHIRE_API_KEY for authentication and SIGNALHIRE_CALLBACK_URL for the Person API. These values are supplied at runtime and must not be echoed or leaked.

2. Always check remaining credits before starting a large enrichment job. Abort or split the job if credits are insufficient.

3. Respect rate and concurrency limits. No more than three concurrent Search API requests【21055727237259†L110-L116】. Do not send more than 600 items through the Person API per minute【821841938681143†L490-L503】. Implement exponential backoff on HTTP 429 responses.

4. Always include a valid callbackUrl when calling the Person API and ensure the connector service is reachable and responsive. The callback must return HTTP 200 within ten seconds or the result may be discarded【821841938681143†L187-L198】.

5. Wait for job completion. After submitting a Person API request, the agent should poll the connector’s job endpoint (described in the README) until it indicates that all results have been received. Only then should the agent proceed to process the CSV data.

6. Handle all status values from the callback. For failed, credits_are_over, timeout_exceeded and duplicate_query, no candidate data will be available; log these cases and move on.

7. Comply with legal and privacy requirements. SignalHire ties API usage to their Terms, Privacy and GDPR pages. Always respect data‑subject rights and opt‑out requests when storing or using contact data【821841938681143†L559-L566】.

By following the above instructions, the agent can safely integrate SignalHire’s prospecting and enrichment capabilities into an OpenClaw workflow.