Tuski API documentation.

Email validation and company search

Base URL: https://tuski.ai. Jobs and searches run asynchronously: start one, poll its status, then retrieve JSON or CSV results. All routes are tenant-scoped. Full schema at /api/v1/openapi.json, or read the generated API reference for every endpoint, parameter and response rendered from that same document.

Errors and retries

Every error body is { "detail": "<message>", "code": "<machine_code>" }. Every error body carries a machine-readable `code` field next to `detail`. Requests sent with the default Python-urllib User-Agent are rejected by the CDN, so set an explicit User-Agent.

Get notified instead of polling

Configure one HTTPS URL per organization in organization settings (admins and owners only) and Tuski calls it when a job or search finishes. Every request is signed so you can verify it came from Tuski.

{
  "event": "validation_job.completed",
  "job_id": 1234,
  "status": "done",
  "total": 500,
  "queued": 0,
  "sent": 500,
  "valid": 421,
  "invalid": 38,
  "unknown": 12,
  "unreachable": 9,
  "mailbox_full": 4,
  "blocked": 6,
  "soft_temp": 5,
  "routing_error": 3,
  "other_bounce": 2,
  "created_at": "2026-09-21T10:02:00Z",
  "finished_at": "2026-09-21T10:07:41Z",
  "links": {
    "status": "https://tuski.ai/api/v1/email-validation/jobs/1234",
    "results": "https://tuski.ai/api/v1/email-validation/jobs/1234/results"
  }
}

{
  "event": "company_search.completed",
  "search_id": "42",
  "status": "succeeded",
  "target": 50,
  "result_count": 48,
  "billable_results": 45,
  "reserved_credits": 50,
  "settled_credits": 45,
  "created_at": "2026-09-21T09:40:00Z",
  "completed_at": "2026-09-21T09:52:18Z",
  "links": {
    "status": "https://tuski.ai/api/v1/discovery/searches/42",
    "results": "https://tuski.ai/api/v1/discovery/searches/42/results"
  }
}

Verify every request before trusting it: read the raw request body, parse t and v1 from Tuski-Signature, reject a timestamp more than 5 minutes old, recompute the HMAC-SHA256 over "<t>." + body, and compare the result to v1 in constant time.

import hashlib
import hmac
import time

def verify_tuski_signature(secret: str, raw_body: bytes, signature_header: str) -> bool:
    # raw_body must be the exact request bytes, read before any JSON parsing.
    parts = dict(part.split("=", 1) for part in signature_header.split(","))
    timestamp, signature = parts["t"], parts["v1"]

    if abs(time.time() - int(timestamp)) > 300:
        return False  # older than 5 minutes - reject as a possible replay

    signed_payload = f"{timestamp}.".encode() + raw_body
    expected = hmac.new(secret.encode(), signed_payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)  # constant-time comparison

const crypto = require('crypto');

function verifyTuskiSignature(secret, rawBody, signatureHeader) {
  // rawBody must be a Buffer of the exact request bytes, read before JSON.parse.
  const parts = Object.fromEntries(signatureHeader.split(',').map((part) => part.split('=')));
  const { t: timestamp, v1: signature } = parts;

  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return false; // older than 5 minutes - reject as a possible replay
  }

  const signedPayload = Buffer.concat([Buffer.from(`${timestamp}.`), rawBody]);
  const expected = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex');
  const expectedBuf = Buffer.from(expected, 'utf8');
  const signatureBuf = Buffer.from(signature, 'utf8');

  // timingSafeEqual throws on a length mismatch, so check that first.
  if (expectedBuf.length !== signatureBuf.length) return false;
  return crypto.timingSafeEqual(expectedBuf, signatureBuf); // constant-time comparison
}

Connect an AI assistant

Tuski exposes a Streamable HTTP MCP server at https://tuski.ai/mcp with tools covering email validation and company search. Claude Desktop and claude.ai connect with an OAuth connector; other clients send the same API key as a Bearer header. A list larger than about 2000 addresses is better uploaded as a file through REST.

Connect Claude Desktop or claude.ai

1. Open Settings, then Connectors, then "Add custom connector".
2. Name it "Tuski" and paste the URL exactly: https://tuski.ai/mcp (no trailing period or slash).
3. Wait for "Checking the server" to finish.
4. On the next screen, under Authentication choose "Sign in now" (the "No sign-in: Detected" mark is expected for Tuski and is not an error).
5. Under OAuth client, choose "Use Claude's published identity" (fall back to "Register automatically" if that option is unavailable).
6. Leave Request headers empty and press Continue.
7. Sign in to Tuski with Google if asked.
8. On the Tuski consent page, choose the organization, tick the permissions you want (validate and export are pre-ticked; discovery and contacts are off until ticked), then press Approve.
9. Back in Claude, ask "what is my Tuski balance" to confirm the connection works.

Troubleshooting

• The URL check fails with a 404. Check the URL for a trailing period or slash, often left over from pasting out of a sentence.
• Sign-in never starts. Remove the connector and add it again, and pick "Sign in now" this time.
• Every tool answers 401. The connector was added with "No sign-in": remove it and re-add it, choosing "Sign in now".
• A connection was revoked in the dashboard. Claude will ask to sign in again the next time a tool is called; this is expected.