API Reference

Overview & Integration Architecture

Talent Kasi is an AI-powered recruitment technology platform designed to transform how organizations discover, evaluate, and hire talent. It provides employers with an end-to-end digital hiring ecosystem for publishing vacancies, receiving and managing applications, AI-powered CV screening and candidate analysis, shortlisting applicants, collaborating with recruitment teams, and making faster, data-driven hiring decisions. Through its developer APIs, integrations, company career pages, analytics, and scalable subscription plans, Talent Kasi enables businesses of all sizes to automate recruitment processes while building more efficient and intelligent talent pipelines.

The Talent-Kasi REST API is a hiring integration API. HR software platforms, custom career portals, and ATS tools can post jobs, submit candidate applications with CV uploads, run and read AI match scores, and receive signed webhooks — without using the HR dashboard. Company settings, team, billing, and API-key management stay on JWT dashboard endpoints; you only need those once, to mint a key.

Credentials & Storage Guidance

Store API keys and webhook secrets in server environment variables — never in frontend client code. A JWT from register or login is only for minting keys; hiring calls use the API key.

Authentication & Key Scopes

Public hiring endpoints authenticate with an API key, not a user session. Pass the secret in either header format on every request. A request lacking a required scope returns 403 Forbidden. JWT tokens from register or login are only used to mint (or manage) keys.

curl -X POST "https://api.talentkasi.com/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dev@acme.com",
    "password": "Password123!",
    "first_name": "Ada",
    "last_name": "Okello",
    "company_name": "Acme Hiring"
  }'

curl -X POST "https://api.talentkasi.com/api/v1/company/api-keys" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ATS integration",
    "environment": "test",
    "scopes": [
      "jobs:read", "jobs:write",
      "applications:read", "applications:write",
      "screening:write", "webhooks:manage"
    ]
  }'

curl -X GET "https://api.talentkasi.com/api/v1/jobs" \
  -H "X-API-Key: tk_live_9f8e7d6c5b4a3f2e1d0c"

Scopes: jobs:read, jobs:write, applications:read, applications:write, screening:write, webhooks:manage. Grant only what the integration needs.

Rate Limits & Rate Limit Headers

Two separate limits apply. Every caller gets a fixed 100 requests per minute burst limit, and on top of that your company has a monthly request quota set by your subscription plan (visible in your dashboard under Account → Billing & Plans). Every response carries the per-minute counters plus X-API-Version: 1.0:

Errors & Status Codes

Errors follow RFC 7807 and are served with Content-Type: application/problem+json. Validation failures add an errors array alongside the summary in detail:

{
  "type": "https://api.talentkasi.com/errors/unauthorized",
  "title": "Unauthorized",
  "statusCode": 401,
  "status": 401,
  "detail": "Missing API key. Pass X-API-Key or Authorization: Bearer tk_live_...",
  "instance": "/api/v1/jobs",
  "timestamp": "2026-08-07T10:15:00.000Z",
  "path": "/api/v1/jobs"
}

Jobs API & Weighted AI Scoring

Create and manage job postings programmatically. Requires jobs:read or jobs:write.

Careers listing is company-wide. Hide or show every open role from the careers page with PATCH /companies/settings (company admin JWT — not an API-key scope).

curl -X GET "https://api.talentkasi.com/api/v1/jobs?status=open" \
  -H "X-API-Key: tk_live_9f8e7d6c5b4a3f2e1d0c"

{
  "count": 14,
  "page": 1,
  "page_size": 20,
  "results": [
    {
      "id": "3f8b1c92-4a7e-4d21-9c53-8e2f6a1b0d47",
      "title": "Senior Full-Stack Engineer",
      "location": "Nairobi, Kenya (Hybrid)",
      "employment_type": "full_time",
      "status": "open",
      "created_at": "2026-08-07T10:00:00.000Z"
    }
  ]
}

curl -X GET "https://api.talentkasi.com/api/v1/jobs/3f8b1c92-4a7e-4d21-9c53-8e2f6a1b0d47" \
  -H "X-API-Key: tk_live_9f8e7d6c5b4a3f2e1d0c"

curl -X POST "https://api.talentkasi.com/api/v1/jobs" \
  -H "X-API-Key: tk_live_9f8e7d6c5b4a3f2e1d0c" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Senior Full-Stack Engineer",
    "location": "Nairobi, Kenya (Hybrid)",
    "employment_type": "full_time",
    "description": "We are seeking an experienced Node.js and React engineer...",
    "requirements": "Bachelor degree in CS, 5+ years TypeScript & Node.js experience",
    "scoring_priority": {
      "skills": 40,
      "experience": 30,
      "education": 15,
      "domain": 15
    },
    "custom_scoring_dimensions": [
      {
        "key": "culture_fit",
        "label": "Culture Fit",
        "description": "Cross-functional teamwork and comfort with ambiguity",
        "weight": 20
      }
    ]
  }'

curl -X PATCH "https://api.talentkasi.com/api/v1/jobs/3f8b1c92-4a7e-4d21-9c53-8e2f6a1b0d47" \
  -H "X-API-Key: tk_live_9f8e7d6c5b4a3f2e1d0c" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Lead Full-Stack Engineer", "salary_range": "$90,000 - $110,000" }'

curl -X PATCH "https://api.talentkasi.com/api/v1/companies/settings" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "careers_visible": false }'

{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "slug": "acme-hiring",
  "name": "Acme Hiring",
  "careers_visible": false,
  "status": "active"
}

curl -X POST "https://api.talentkasi.com/api/v1/jobs/3f8b1c92-4a7e-4d21-9c53-8e2f6a1b0d47/close" \
  -H "X-API-Key: tk_live_9f8e7d6c5b4a3f2e1d0c"

{
  "job": {
    "id": "3f8b1c92-4a7e-4d21-9c53-8e2f6a1b0d47",
    "status": "closed",
    "updated_at": "2026-08-07T16:00:00.000Z"
  },
  "auto_rejected": 4
}

curl -X DELETE "https://api.talentkasi.com/api/v1/jobs/3f8b1c92-4a7e-4d21-9c53-8e2f6a1b0d47" \
  -H "X-API-Key: tk_live_9f8e7d6c5b4a3f2e1d0c"

Applications & Candidate CV Ingestion

Submit candidates and review applicants, including CV uploads that automatically trigger AI screening. Reading requires applications:read; submitting and status changes require applications:write.

Submission is multipart/form-data and first_name, last_name, email, phone and cv are all required — omitting any of them returns 400. The CV must be a PDF or DOCX. Any extra questions you configured on the job's application form go in optional_fields as a JSON object. Apply still works when the company has hidden jobs from its careers page (careers_visible: false).

curl -X POST "https://api.talentkasi.com/api/v1/jobs/3f8b1c92-4a7e-4d21-9c53-8e2f6a1b0d47/applications" \
  -H "X-API-Key: tk_live_9f8e7d6c5b4a3f2e1d0c" \
  -F "first_name=Amina" \
  -F "last_name=Ochieng" \
  -F "email=amina.ochieng@example.com" \
  -F "phone=+254712345678" \
  -F "cv=@/path/to/resume.pdf"

{
  "id": "b7d4e2f1-9c8a-4e35-b012-5f7a3c9d1e64",
  "job_id": "3f8b1c92-4a7e-4d21-9c53-8e2f6a1b0d47",
  "first_name": "Amina",
  "last_name": "Ochieng",
  "email": "amina.ochieng@example.com",
  "phone": "+254712345678",
  "status": "received",
  "created_at": "2026-08-07T12:00:00.000Z"
}

curl -X GET "https://api.talentkasi.com/api/v1/jobs/3f8b1c92-4a7e-4d21-9c53-8e2f6a1b0d47/applications?page=1&page_size=20" \
  -H "X-API-Key: tk_live_9f8e7d6c5b4a3f2e1d0c"

{
  "count": 1,
  "page": 1,
  "page_size": 20,
  "results": [
    {
      "id": "b7d4e2f1-9c8a-4e35-b012-5f7a3c9d1e64",
      "job_id": "3f8b1c92-4a7e-4d21-9c53-8e2f6a1b0d47",
      "first_name": "Amina",
      "last_name": "Ochieng",
      "email": "amina.ochieng@example.com",
      "status": "screened",
      "created_at": "2026-08-07T12:00:00.000Z"
    }
  ]
}

curl -X GET "https://api.talentkasi.com/api/v1/applications/b7d4e2f1-9c8a-4e35-b012-5f7a3c9d1e64" \
  -H "X-API-Key: tk_live_9f8e7d6c5b4a3f2e1d0c"

{
  "id": "b7d4e2f1-9c8a-4e35-b012-5f7a3c9d1e64",
  "job_id": "3f8b1c92-4a7e-4d21-9c53-8e2f6a1b0d47",
  "first_name": "Amina",
  "last_name": "Ochieng",
  "email": "amina.ochieng@example.com",
  "status": "shortlisted",
  "cv_download_url": "https://s3.talentkasi.com/resumes/amina_cv.pdf?X-Amz-Expires=3600...",
  "screening_result": {
    "match_score": 88,
    "justification": "Six years of TypeScript and Node.js with strong system architecture background.",
    "strengths": ["6+ years Node.js & React", "TypeScript expert"],
    "gaps": ["No direct AWS DevOps certification"],
    "dimension_scores": {
      "skills": { "score": 95, "evidence": "Shipped three production React/Node platforms" }
    },
    "referees": [
      { "name": "J. Mwangi", "role": "Engineering Manager", "contact": "+254700000000" }
    ]
  }
}

curl -X PATCH "https://api.talentkasi.com/api/v1/applications/b7d4e2f1-9c8a-4e35-b012-5f7a3c9d1e64" \
  -H "X-API-Key: tk_live_9f8e7d6c5b4a3f2e1d0c" \
  -H "Content-Type: application/json" \
  -d '{ "status": "shortlisted" }'

Candidate Hiring Status Lifecycle

These six values are the complete set that PATCH /applications/:id accepts — anything else returns 400. Most are managed by the screening pipeline; in practice you only ever set shortlisted or rejected yourself, and doing so emails the candidate. No status is terminal, so a decision can be reversed.

AI Screening Results

Fetch AI match scores, fit recommendations (STRONG_FIT at 75 and above, MODERATE_FIT at 50-74, WEAK_FIT below 50), dimension breakdown, strengths and gaps for every applicant on a job. Queue or re-run screening with screening:write. Referees extracted from a CV are returned by GET /applications/:id rather than here. Reading results requires applications:read.

curl -X GET "https://api.talentkasi.com/api/v1/jobs/3f8b1c92-4a7e-4d21-9c53-8e2f6a1b0d47/screening-results" \
  -H "X-API-Key: tk_live_9f8e7d6c5b4a3f2e1d0c"

curl -X POST "https://api.talentkasi.com/api/v1/jobs/3f8b1c92-4a7e-4d21-9c53-8e2f6a1b0d47/screening/run" \
  -H "X-API-Key: tk_live_9f8e7d6c5b4a3f2e1d0c"

{
  "is_sandbox": false,
  "count": 1,
  "page": 1,
  "page_size": 20,
  "results": [
    {
      "applicant_id": "b7d4e2f1-9c8a-4e35-b012-5f7a3c9d1e64",
      "first_name": "Amina",
      "last_name": "Ochieng",
      "email": "amina.ochieng@example.com",
      "status": "screened",
      "applied_at": "2026-08-07T12:00:00.000Z",
      "screening": {
        "match_score": 88,
        "recommendation": "STRONG_FIT",
        "justification": "Six years of TypeScript and Node.js with a strong system architecture background.",
        "strengths": ["6+ years Node.js & React", "TypeScript expert"],
        "gaps": ["No direct AWS DevOps certification"],
        "dimension_scores": {
          "skills": { "score": 95, "evidence": "Shipped three production React/Node platforms" },
          "experience": { "score": 90, "evidence": "6 years across two scale-ups" }
        }
      }
    }
  ]
}

Registering Outbound Webhooks

Register an HTTPS endpoint with POST /webhooks (webhooks:manage) or from the dashboard under Developer & API. Save the whsec_... signing secret shown once when the endpoint is created.

curl -X POST "https://api.talentkasi.com/api/v1/webhooks" \
  -H "X-API-Key: tk_live_9f8e7d6c5b4a3f2e1d0c" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/talentkasi",
    "events": ["application.received", "screening.completed"]
  }'

Every delivery uses the same envelope, so a handler written against the Send test event button (event test.event) works unchanged for real events:

{
  "event": "screening.completed",
  "timestamp": "2026-08-07T12:00:05.000Z",
  "company_id": "8c1f0a53-6b2d-4f19-9a70-1e4c7b8d5a02",
  "data": { }
}

application.received
{ "application_id", "job_id", "job_title", "first_name", "email" }

application.status_changed
{ "application_id", "job_id", "job_title", "first_name", "email",
  "old_status", "new_status" }

screening.completed
{ "application_id", "job_id", "status",
  "match_score": 88, "recommendation": "STRONG_FIT" }

job.published
{ "job_id", "title", "location", "employment_type", "public_url" }

job.closed
{ "job_id", "title", "status": "closed" | "archived", "auto_rejected": 4 }

A few things worth knowing before you subscribe. screening.completed is deliberately thin — fetch GET /applications/:id when you need the full result — and match_score and recommendation are null when scoring failed. Closing a job emits one application.status_changed per auto-rejected applicant in addition to job.closed, so a busy job produces a burst. And job.published fires when a job first becomes open, including when a draft is opened later or a closed job is re-opened.

Deliveries time out after 10 seconds and are attempted up to 3 times with exponential backoff. After 5 consecutive failed deliveries an endpoint is automatically deactivated and stops receiving events until you re-register it, so watch the delivery log after deploying changes to your handler.

Verifying HMAC Webhook Signatures

Every webhook delivery includes an HMAC-SHA256 signature. Follow this 7-step checklist to verify signatures safely:

1. Read X-TalentKasi-Signature and X-TalentKasi-Timestamp from request headers.
2. Read the raw request body as a string before JSON parsing.
3. Reject requests where the timestamp is older than 300 seconds (replay attack protection).
4. Compute HMAC-SHA256(webhook_secret, "$${timestamp}.${raw_body}").
5. Perform constant-time comparison (timingSafeEqual) against the header digest.
6. Return any 2xx status to acknowledge receipt — anything else counts as a failure and is retried up to 3 times.
7. Ensure your handler is idempotent — handle duplicate event delivery gracefully.

# Verify HMAC-SHA256 signature (shown in Node.js — see tabs for Python/PHP)
import crypto from 'crypto';

function verifyWebhook(secret, rawBody, signature, timestamp) {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${timestamp}.${rawBody}`).digest('hex');
  return signature === `t=${timestamp},v1=${expected}`;
}

Full Production Webhook Server Implementations

Copyable, full end-to-end production webhook server implementations in Node.js (Express with raw body parsing), Python (Flask), and PHP:

// Complete Node.js (Express) Webhook Server
import express from 'express';
import crypto from 'crypto';

const app = express();

app.post('/webhooks/talentkasi', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  const sig = req.headers['x-talentkasi-signature'];
  const ts = req.headers['x-talentkasi-timestamp'];
  const secret = process.env.TALENTKASI_WEBHOOK_SECRET;

  const expected = crypto.createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  if (sig !== `t=${ts},v1=${expected}`) return res.sendStatus(401);

  const event = JSON.parse(rawBody);
  if (event.event === 'screening.completed') {
    console.log('Screened', event.data.application_id, event.data.match_score, event.data.recommendation);
  }
  res.sendStatus(200);
});

Security Best Practices

• Server-Side Execution Only: Never place API keys (tk_live_... or tk_test_...) or webhook secrets in client-side code, mobile apps, or public Git repos. If a key leaks, disable or delete it in the Developer Portal and generate a new one.
• Raw Body Signature Verification: Always verify signatures against raw body strings before parsing JSON to prevent payload tampering.
• Replay Protection: Validate that X-TalentKasi-Timestamp is within 5 minutes of your server's clock.
• HTTPS Enforcement: All webhook endpoints must use TLS/HTTPS in production.
• Environment Variable Isolation: Store TALENTKASI_API_KEY and TALENTKASI_WEBHOOK_SECRET in environment variables or a secret manager.

Sandbox Testing Mode

Keys starting with tk_test_... are for building and debugging. They never count against your monthly API quota, and they never read or write your live company.

Manage keys from the live Developer Portal: disable or delete a key there. There is no separate revoke action. The sandbox dashboard cannot mint keys of its own.

API Glossary

Integration Setup Checklist

1. Register with POST /auth/register (or sign in to the dashboard). Create a tk_test_... key via POST /company/api-keys with environment: "test" — this works on Free. Isolated sandbox, no monthly quota, simulated AI.
2. Store the secret in backend environment variables (e.g. TALENTKASI_API_KEY). Use the API key, not the JWT, for hiring calls.
3. Create jobs with POST /api/v1/jobs. Optionally upload images with POST /api/v1/jobs/images.
4. Submit CVs via POST /api/v1/jobs/:jobId/applications. Queue or re-run screening with POST /jobs/:id/screening/run (screening:write).
5. Register a webhook with POST /api/v1/webhooks and verify signatures using the whsec_... secret.
6. Confirm sandbox jobs and applicants stay off the live dashboard, then cut over to a tk_live_... key (Growth or Enterprise) for real candidates.