signalhire – OpenClaw Skill

---

name: signalhire description: Prospect and enrich contacts via the SignalHire API (Search, Person and Credits) metadata: openclaw: # The skill only loads when a valid API key and callback URL are provided. The # primary environment variable is used to inject the secret without ever # exposing it in the instructions. The callback URL should point to the # connector service exposed publicly via a tunnel or reverse proxy. requires: env: SIGNALHIRE_API_KEY,SIGNALHIRE_CALLBACK_URL primaryEnv: SIGNALHIRE_API_KEY

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.

SignalHire OpenClaw skill

This repository contains everything needed to run a complete SignalHire integration as an OpenClaw skill. It includes a concise set of agent instructions (SKILL.md) and a small connector service that handles asynchronous callbacks from the SignalHire Person API. The connector writes results into CSV files on the local filesystem so you can import them into your CRM or analysis pipeline.

Prerequisites

• Operating system: Ubuntu or any Linux distribution with Python 3.8+.
• Python packages: The connector depends on flask only. Install it with pip install flask.
• Environment variables:
  • SIGNALHIRE_API_KEY – your SignalHire API key. Required for all API calls.
  • SIGNALHIRE_CALLBACK_URL – a publicly reachable HTTPS endpoint that forwards to the local connector. SignalHire posts results to this address after processing Person API requests. It must respond with HTTP status 200 within ten seconds to be considered successful【821841938681143†L187-L198】.
  • SIGNALHIRE_OUTPUT_DIR – the directory where CSV files will be written. Defaults to ./data/signalhire if not set.

You will also need a way to expose your local connector to the internet. A free Cloudflare Tunnel is the simplest option: it creates a secure public URL and forwards requests to your local machine without opening firewall ports.

Running the connector

1. Install dependencies:

   python3 -m pip install flask
   

2. Start the connector:

   export SIGNALHIRE_OUTPUT_DIR=/opt/openclaw/data/signalhire
   python3 -m signalhire.connector.main --port 8787
   

   The connector listens on the port you specify (default 8787) and exposes two endpoints:

   • POST /signalhire/callback – receives callback payloads from SignalHire. It writes or appends rows to a CSV file named results_<requestId>.csv in the output directory. The callback endpoint must be mapped to your public SIGNALHIRE_CALLBACK_URL (e.g., via a Cloudflare Tunnel or reverse proxy). SignalHire will retry up to three times if the callback fails or times out【821841938681143†L187-L198】.
   • GET /signalhire/jobs/<requestId> – returns a JSON object describing whether the job has produced any rows and how many. Once the row count matches the number of items you submitted, the job is ready and the CSV can be processed.

3. Expose the callback:

   If you use Cloudflare Tunnel, run something like:

   cloudflared tunnel run my-signalhire
   # This prints a public URL such as https://red-example.trycloudflare.com
   

   Set SIGNALHIRE_CALLBACK_URL to https://red-example.trycloudflare.com/signalhire/callback.

CSV output schema

The connector writes one CSV per Person API request. A consolidated results_all.csv is also maintained in the same directory. Each row in the CSV includes the following fields:

column	description
request_id	Unique ID returned by the Person API and sent back in the callback header【821841938681143†L200-L208】.
input_type	Type of the input: linkedin, email, phone or uid.
input_value	The identifier you requested.
status	One of success, failed, credits_are_over, timeout_exceeded or duplicate_query【821841938681143†L239-L249】.
full_name	Candidate’s full name (empty if status is not success).
title	Current job title (if available).
company_name	Current company (if available).
location	Candidate’s primary location.
linkedin_url	LinkedIn profile URL (if present).
emails	Semicolon‑separated list of email addresses.
phones	Semicolon‑separated list of phone numbers.
source	Always set to signalhire.
received_at_utc	Timestamp when the callback was processed.

The per‑request CSV is named results_<requestId>.csv, where <requestId> comes from the Person API response. A global file results_all.csv is updated with every callback for convenience.

Usage in an OpenClaw workflow

1. Agent loads the skill: When OpenClaw starts, it reads SKILL.md. If SIGNALHIRE_API_KEY and SIGNALHIRE_CALLBACK_URL are present in the environment, the skill is enabled and the agent can call its actions.

2. Check credits: The agent calls signalhire_check_credits to determine how many credits remain【821841938681143†L505-L529】. If the account has too few credits for the upcoming job, it should warn the user or split the job.

3. Search: To identify prospects without spending credits, the agent invokes signalhire_search_by_query with filters such as job title, location and keywords【21055727237259†L120-L177】. Only three concurrent search requests are allowed【21055727237259†L110-L116】, so the agent must throttle itself. The search action returns a list of UIDs or LinkedIn URLs that can be passed to the Person API.

4. Enrich: The agent invokes signalhire_enrich_contacts with up to 100 identifiers and waits for a requestId response【821841938681143†L126-L134】. The agent then polls GET /signalhire/jobs/<requestId> until the CSV is ready. Once ready, the agent reads the CSV from disk and uses it to populate leads in your downstream system.

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

Legal and privacy considerations

SignalHire ties API usage to its Terms, Privacy Policy and GDPR pages. Retrieved contact information must be handled responsibly and used only for legitimate purposes. Always honour opt‑out and removal requests. The documentation emphasises the importance of a valid callback server and a prompt 200 OK response to avoid data loss【821841938681143†L187-L198】.

Contact

For more information about the SignalHire API, please refer to the official documentation at https://www.signalhire.com/api/person. If you require assistance integrating this skill into your OpenClaw deployment, please open an issue or contact your system administrator.