Recruiter spam is the single biggest complaint on every professional network. On LinkedIn, anyone can InMail you. On TandamConnect, recruiters use the Ping API β a structured, rate-limited system that respects candidate preferences and gives both sides transparency. This guide covers everything you need to integrate with the v1 Ping API.
A Ping is a structured outreach from a recruiter to a candidate. Unlike free-form messages, Pings have required fields β role title, company, compensation range, and a brief note β so candidates get the information they need to make a decision without back-and-forth. Pings are delivered to the candidate's dashboard and optionally to their email.
import { TandamConnect } from "@tandamconnect/sdk";
const tc = new TandamConnect({ apiKey: "tc_live_..." });
const ping = await tc.pings.send({
candidate: "username-or-id",
role: "Senior Platform Engineer",
company: "Acme Corp",
compensation: { min: 180000, max: 240000, currency: "USD" },
location: "Remote (US)",
note: "We're building the next-gen deployment platform and your agent orchestration work caught our eye.",
});
console.log(ping.id); // "ping_8k2m4n7x"
console.log(ping.status); // "delivered"To prevent spam, the Ping API enforces strict rate limits. Free-tier recruiter accounts can send 10 pings per day. Pro accounts get 50. Enterprise accounts get 200. Limits reset at midnight UTC. Every response includes rate limit headers so you can track your usage.
HTTP/1.1 200 OK
X-RateLimit-Limit: 50
X-RateLimit-Remaining: 47
X-RateLimit-Reset: 1741305600
Content-Type: application/jsonIf you exceed your limit, the API returns a 429 status with a Retry-After header. The SDK handles this automatically with exponential backoff, but if you're calling the REST API directly, you'll need to implement retry logic yourself.
Instead of polling for ping responses, you can register a webhook URL in your developer dashboard. We'll send a POST request whenever a candidate responds to one of your pings β whether they accept, decline, or request more information. Webhook payloads are signed with HMAC-SHA256 so you can verify authenticity.
// Webhook handler (Express example)
app.post("/webhooks/tandamconnect", (req, res) => {
const signature = req.headers["x-tc-signature"];
const isValid = tc.webhooks.verify(req.body, signature);
if (!isValid) return res.status(401).send("Invalid signature");
const { event, ping } = req.body;
// event: "ping.accepted" | "ping.declined" | "ping.info_requested"
if (event === "ping.accepted") {
// Candidate accepted β open a conversation thread
console.log(`${ping.candidate} accepted ping for ${ping.role}`);
}
res.status(200).send("OK");
});The official @tandamconnect/sdk package wraps the REST API with full TypeScript types, automatic retries, and built-in webhook verification. Install it from npm and initialize with your API key. The SDK supports both ESM and CommonJS.
To start using the Ping API, sign up for a recruiter account at tandamconnect.com, generate an API key in your developer dashboard, and install the SDK. The free tier gives you 10 pings per day β enough to test your integration and start reaching out to candidates. If you need higher limits, upgrade to Pro or contact us for Enterprise pricing.
How we built a lightweight protocol for AI agents to register, report heartbeats, and relay status uβ¦
Read more βEngineeringStop using AI agents in isolation. Learn how to compose multiple agents into a coordinated team thatβ¦
Read more βEngineeringA hands-on guide to the best open-source AI coding tools β Aider, Continue.dev, OpenHands, SWE-agentβ¦
Read more β