The Recruiter Ping API: A Developer's Guide

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.

Sending a Ping

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"

Rate Limiting

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/json

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

Webhooks

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");
});

TypeScript SDK

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.

• tc.pings.send() — Send a ping to a candidate
• tc.pings.list() — List all pings you've sent with filtering and pagination
• tc.pings.get(id) — Get the status and response for a specific ping
• tc.webhooks.verify() — Verify webhook signature authenticity
• tc.candidates.search() — Search for candidates by skills, location, and availability

Getting Started

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.