A REST API and signed webhooks for pushing screened, scored candidates into your own ATS. Every request below is live — edit the parameters and send it against a working sandbox account, no signup required.
Every console on this page is pre-filled with a read/write sandbox API key (sk_live_d0c50000…) scoped to a demo agency with real seed data. Swap in your own key from API & Webhooks in your ChatSieve account settings once you're ready to test against your own tenant. The sandbox key is public and shared — don't rely on its data staying put.
Every request authenticates with an API key generated from API & Webhooks in your account settings. Keys are shown once at creation — store them securely.
curl https://api.chatsieve.example.com/api/v1/candidates \ -H "Authorization: Bearer sk_live_..."
All endpoints are scoped to the agency that owns the key — there is no way to read or write another tenant's data with a valid key. Requests without a valid Authorization header return 401.
GET /api/v1/candidates — filter by status or vacancy, most recent first.
/api/v1/candidatesGET /api/v1/candidates/:id — full detail including WhatsApp message history, documents, and score factors. Paste an id from the list above.
/api/v1/candidates/:idPOST /api/v1/candidates/:id/status — accepting or rejecting fires the matching webhook event to any subscribed endpoint.
/api/v1/candidates/:id/statusstatus must be one of: NEW, SCREENING, PENDING_REVIEW, ACCEPTED, REJECTED
GET /api/v1/vacancies — every open role for the authenticated agency, with a candidate count.
/api/v1/vacanciesPOST /api/v1/vacancies — the minimum fields needed to start routing applicants into a screening flow.
/api/v1/vacanciesPOST /api/v1/bulk-screening — sends the opening WhatsApp screening message to every new candidate on a vacancy (or a specific candidate_ids list). Messages send for real once WhatsApp credentials are configured; until then they're recorded with a simulated status.
/api/v1/bulk-screeningRegister an endpoint from API & Webhooks in your account settings, choosing which events to receive. Each endpoint gets its own signing secret, shown once at creation.
candidate.acceptedcandidate.rejecteddocument.flagged{
"event": "candidate.accepted",
"created_at": "2026-07-11T10:00:00.000Z",
"data": {
"candidate_id": "clx_9f2a7b",
"name": "Emily Carter",
"vacancy_id": "vac_platform_eng",
"score": 92
}
}Every delivery includes an X-ChatSieve-Signature header — an HMAC-SHA256 hex digest of the raw request body, keyed with your endpoint's signing secret. Always verify against the raw bytes, before any JSON parsing, and use a constant-time comparison.
const crypto = require("crypto");
function isValidSignature(rawBody, signatureHeader, signingSecret) {
const expected = crypto
.createHmac("sha256", signingSecret)
.update(rawBody)
.digest("hex");
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signatureHeader)
);
}
// In your webhook route handler:
app.post("/hooks/chatsieve", express.raw({ type: "*/*" }), (req, res) => {
const signature = req.header("X-ChatSieve-Signature");
if (!isValidSignature(req.body, signature, process.env.CHATSIEVE_WEBHOOK_SECRET)) {
return res.status(401).send("Invalid signature");
}
const event = JSON.parse(req.body);
// handle event.event, event.data …
res.status(200).send("ok");
});Sends a signed sample payload to any URL you provide, so you can test your receiver without waiting for a real candidate or document event. Get a free throwaway URL from webhook.site to see it land.
The current API version is v1, under /api/v1/*. Breaking changes will ship under a new version prefix rather than changing existing behavior in place. Questions? Talk to us.
Generate a live API key from your account in under a minute.
AI-powered candidate screening over WhatsApp, built for recruitment agencies.