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.

1. Always check remaining credits before starting a large enrichment job.

Abort or split the job if credits are insufficient.

1. 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.

1. 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】.

1. 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.

1. 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.

1. 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.