SDKs

Two official clients, one file each, zero dependencies. Download the file, drop it into your project, done. No package manager required - they are plain source you own.

Both clients handle the whole API contract for you:

• Bearer auth and the response envelope (data unwrapping, typed errors with code, status, request_id)
• Auto-generated Idempotency-Key on every POST (the API requires one on mutating POSTs)
• Cursor pagination, including an iterator that follows next_cursor to exhaustion
• Retry with backoff on 429 and 5xx, honouring Retry-After
• Async task polling (waitForTask / wait_for_task) for 202 responses
• Webhook signature verification (HMAC-SHA256, constant-time compare, replay-window check)

TypeScript

import { Lovelio, verifyWebhookSignature } from './lovelio'

const client = new Lovelio({ apiKey: process.env.LOVELIO_API_KEY! })

// Lists return { data, meta }; iterate() pages for you
const { data: active } = await client.jobs.list({ status: 'active' })
for await (const candidate of client.candidates.iterate()) {
  console.log(candidate.id)
}

// Async creates return a task handle - wait for the pipeline to finish
const created = await client.jobs.create({
  title: 'Senior Property Manager',
  client_id: 'cli_...',
})
await client.waitForTask(created.task_id)

// Actions run through batch
await client.batch([
  { op: 'add_note', payload: { candidate_id: 'cnd_...', note: 'Called, keen.' } },
])

// In your webhook handler - verify against the RAW body
const ok = await verifyWebhookSignature({
  payload: rawBody,
  signature: req.headers['x-lovelio-signature'],
  timestamp: req.headers['x-lovelio-timestamp'],
  secret: process.env.LOVELIO_WEBHOOK_SECRET!,
})

Python

from lovelio import Lovelio, verify_webhook_signature

client = Lovelio(api_key=os.environ["LOVELIO_API_KEY"])

active = client.jobs.list(status="active")["data"]
for candidate in client.candidates.iterate():
    print(candidate["id"])

created = client.jobs.create(title="Senior Property Manager", client_id="cli_...")
client.wait_for_task(created["task_id"])

client.batch([
    {"op": "add_note", "payload": {"candidate_id": "cnd_...", "note": "Called, keen."}},
])

ok = verify_webhook_signature(raw_body, signature_header, timestamp_header, webhook_secret)

Errors

Both clients raise one exception type on any non-2xx: LovelioError with code (the API's stable error code, e.g. VALIDATION_ERROR, INSUFFICIENT_SCOPE), status, message, and request_id for support. 429 and 5xx are retried automatically before the error reaches you.

Hand this to Claude

Download https://lovelio.ai/sdk/lovelio.ts into the project, then use it with
our LOVELIO_API_KEY to list active jobs, add today's shortlisted candidates to
each, and print the ids it created. Wait for any task the API returns.