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

Interact with the SignalHire API to enrich and verify professional contacts. Use this skill when asked to find email addresses, phone numbers, or search for professional profiles and companies using SignalHire. Supports Person API for comprehensive profile/contact data and Search API for lead genera

SignalHire API Skill

This skill provides context and instructions for using the SignalHire API to retrieve contact information (emails, phone numbers, social media profiles) from a global database of professionals.

Authentication

To access the SignalHire API, an API key is required. The API key must be included in the apikey request header.

If the user hasn't provided their SignalHire API key in their request or environment, ask them to provide it before making API calls. Ensure it is kept secure and not exposed publicly.

Endpoints

1. Person API

Retrieves comprehensive profile and full contact details about a specific individual based on unique identifiers (e.g., LinkedIn® profile links, email addresses, phone numbers, or ID).

• Use Case: Find a specific person's contact info.
• Rate Limit: 600 items per minute.
• Callback URL: The Person API is asynchronous — SignalHire POSTs the result to a callback URL you provide. See Callback Setup below.

2. Search API

Searches for individuals or companies using various filters (e.g., job title, location, industry). Returns a brief overview of information without contact details.

• Use Case: Lead generation, talent acquisition, market research.
• Rate Limit: 1 concurrent request.

---

Callback Setup

The Person API is asynchronous: you submit a request with a callbackUrl, and SignalHire POSTs the enriched result to that URL when ready.

Requirements

• A publicly reachable HTTPS endpoint that accepts POST requests with JSON body.
• A shared secret in the callback URL as a query parameter (e.g. ?k=<secret>), because SignalHire controls the outbound request and cannot set custom headers.

Step 1 — Deploy a webhook receiver

You need an HTTP server that:

1. Accepts POST /signalhire/callback?k=<secret>
2. Validates the k parameter against your stored secret
3. Saves the JSON payload to a known file (e.g. signalhire_result.json) so the agent can read it back

A minimal Flask example:

python

import hmac, os
from flask import Flask, request, jsonify
import json

app = Flask(__name__)
SECRET = os.environ["SIGNALHIRE_WEBHOOK_SECRET"]

@app.before_request
def auth():
    if request.method == "POST":
        k = request.args.get("k", "")
        if not hmac.compare_digest(k, SECRET):
            return jsonify({"error": "unauthorized"}), 403

@app.route("/signalhire/callback", methods=["POST"])
def callback():
    payload = request.get_json()
    with open("signalhire_result.json", "w") as f:
        json.dump(payload, f, indent=2)
    return jsonify({"status": "accepted"}), 200

if __name__ == "__main__":
    app.run(host="127.0.0.1", port=8000)

Step 2 — Generate a shared secret

bash

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

Store this value as SIGNALHIRE_WEBHOOK_SECRET in your server's environment.

Step 3 — Set SIGNALHIRE_CALLBACK_URL

Construct the full callback URL including the secret:

text

https://<your-domain>/signalhire/callback?k=<your-secret>

Store it as the environment variable SIGNALHIRE_CALLBACK_URL, or in a config file your agent reads. Never hardcode it in source files — rotate the secret by updating it in one place.

Example (shell / .env file):

text

SIGNALHIRE_CALLBACK_URL=https://your-domain.com/signalhire/callback?k=your-secret-here
SIGNALHIRE_WEBHOOK_SECRET=your-secret-here

Step 4 — Use it in requests

Read SIGNALHIRE_CALLBACK_URL from the environment at runtime and pass it as callbackUrl in every Person API request body. Do not hardcode the URL.

python

import os
callback_url = os.environ["SIGNALHIRE_CALLBACK_URL"]

Step 5 — Read the result

After submitting the enrichment request, poll or wait for signalhire_result.json to be written by your webhook server, then read and return the data to the user.

---

Handling Responses & Credits

Credits

The HTTP response headers provide the total remaining credits in the X-Credits-Left header. Always keep track of this if possible and alert the user if they are running low.

Common HTTP Status Codes

• 200: Request is completed successfully, data collected.
• 201: Request is accepted, server started collecting data.
• 204: Request is still in progress.
• 401: Authentication failed (invalid API key).
• 402: Out of credit limit.
• 403: Account disabled or querying unauthorized request status.
• 406: Requested more than the maximum allowed items (limit is 100).
• 422: Incorrect or malformed parameters.
• 429: Rate limit exceeded.

Execution Pattern

When the user asks you to search for a contact or company using SignalHire:

1. Verify you have the apikey.
2. Determine if the goal is enrichment (Person API) or discovery (Search API).
3. For Person API: read SIGNALHIRE_CALLBACK_URL from the environment; if unset, prompt the user to complete Callback Setup above before proceeding.
4. Use the exec tool to run a curl or fetch script passing the apikey header (-H "apikey: $API_KEY") and the callbackUrl in the request body.
5. Wait for the callback to arrive, then read signalhire_result.json and return the findings to the user cleanly.