Public Jobs API

Why It Matters

Kit’s hosted career portal and embeddable widget cover most needs. But if you want full control over design — a bespoke careers site, a custom landing page per role, or a job board that matches your product — the Public Jobs API lets you read your published jobs and submit applications straight into your Kit pipeline, while Kit keeps owning screening, stages, interviews, and candidate communication.

There’s also an official TypeScript SDK and a one-click Next.js template so you can ship a custom job site in minutes — or skip both and call the REST endpoints below directly with any HTTP client.

API Keys

Create a key pair under Hiring → Career Portal → Public API Keys. Each pair has:

• Publishable key (pk_…) — safe to ship in a browser. It can read published jobs and submit applications, nothing else, and it never exposes candidate data. Before it can submit applications or request presigned uploads, you must configure at least one bot defence — an origin allowlist or your own Cloudflare Turnstile widget — otherwise those requests are rejected with 403 bot_protection_required. Reading jobs works without it.
• Secret key (sk_…) — for server-side use only (e.g. a Next.js Server Action). It skips the browser origin/Turnstile checks. Never expose it in client-side code. Neither key can read candidate PII.

The secret key is shown only once, when created or rotated. Rotate it any time from the key’s settings page; the previous secret stops working immediately.

Authenticate every request with a bearer header:

Authorization: Bearer sk_your_secret_key

Endpoints

Base URL: https://startupkit.app (or your career custom domain).

List published jobs

GET /api/public/v1/jobs?department=&location=&employment_type=&remote=&page=&per_page=

Returns only published roles for your account.

{
  "data": [
    {
      "id": "JdK2hQ8…",
      "title": "Senior Rails Developer",
      "department": "Engineering",
      "location": "Remote",
      "employment_type": "full_time",
      "remote": true,
      "published_at": "2026-06-01T12:00:00Z",
      "url": "https://careers.yourco.com/JdK2hQ8…",
      "salary": { "min": 120000, "max": 160000, "currency": "USD", "period": "YEAR" }
    }
  ],
  "pagination": { "current_page": 1, "total_pages": 3, "total_count": 42, "per_page": 20 }
}

The id is the job’s public token — use it for the detail and apply endpoints.

Get a job + its application form

GET /api/public/v1/jobs/:public_token

Returns the job plus an application_form describing exactly which fields and questions to render, the consent disclosure to show, whether a resume is required plus its accepted types/size, and whether Turnstile is required.

{
  "id": "JdK2hQ8…",
  "title": "Senior Rails Developer",
  "description_html": "<p>We're hiring…</p>",
  "accepting_applications": true,
  "stages": [{ "name": "Application Review", "type": "application_form" }],
  "application_form": {
    "fields": [
      { "name": "cover_letter", "type": "textarea", "label": "Cover letter", "required": false }
    ],
    "questions": [
      { "key": "why_us", "type": "text", "prompt": "Why do you want to join?", "required": true, "max_length": 2000 }
    ],
    "consent_disclosure_html": "<p>By applying you agree…</p>",
    "resume": {
      "required": false,
      "content_types": ["application/pdf", "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"],
      "max_byte_size": 10485760
    },
    "turnstile": { "required": false, "sitekey": null }
  }
}

required flags are enforced server-side. When resume.required is true, an application without a resume_signed_id is rejected with 422 validation_failed — the same happens for any unanswered field or question marked required: true. If you render the form dynamically from this schema, honor these flags so candidates don’t hit a rejection after filling everything in.

Upload a resume (presigned)

Resumes upload directly to storage, so they never pass through your server (avoiding serverless body-size limits).

POST /api/public/v1/direct_uploads
{ "blob": { "filename": "cv.pdf", "byte_size": 102400, "checksum": "<base64 MD5>", "content_type": "application/pdf" } }

{
  "signed_id": "eyJf…",
  "direct_upload": { "url": "https://…s3…", "headers": { "Content-Type": "application/pdf", "Content-MD5": "…" } }
}

PUT the file bytes to direct_upload.url with the returned headers, then pass the signed_id as resume_signed_id when you submit the application.

Submit an application

POST /api/public/v1/jobs/:public_token/applications
{
  "application": {
    "email": "[email protected]",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "phone": "+1 555 0100",
    "responses": { "cover_letter": "…", "why_us": "…" },
    "resume_signed_id": "eyJf…"
  },
  "turnstile_token": "<token>"
}

Returns 201 with a minimal, PII-free confirmation:

{ "id": "app_9fQ…", "status": "submitted", "job": "JdK2hQ8…", "submitted_at": "2026-06-11T09:30:00Z" }

turnstile_token is only needed for browser (pk_) submissions when the key has Turnstile configured; server-side (sk_) calls skip it.

Talent Pool

Not everyone who likes your company fits an open role today. The talent pool captures those people — email, LinkedIn, optionally a CV — so you can invite them when the right role opens. Entries land unverified: Kit emails a confirmation link, and nobody joins your pool through this endpoint until they click it. (Admins can also import CVs directly, which is a separate door with its own rules.)

A talent-pool signup is someone asking you to keep their details on file with no job to apply for, so it needs explicit consent — a real ticked checkbox, not a disclosure you show them. Kit rejects a public signup that omits it. An admin import records a lawful-basis attestation instead, because nobody is there to tick anything.

Read the intake form

GET /api/public/v1/talent_pool

{
  "accepting_signups": true,
  "consent": {
    "required": true,
    "disclosure_html": "<p>Keep my details on file for 24 months…</p>",
    "retention_months": 24,
    "privacy_policy_url": "https://yourco.com/privacy"
  },
  "fields": [
    { "name": "email", "required": true },
    { "name": "linkedin_url", "required": false },
    { "name": "resume_signed_id", "required": false }
  ],
  "resume": {
    "required": false,
    "content_types": ["application/pdf", "application/msword", "application/vnd.openxmlformats-officedocument.wordprocessingml.document"],
    "max_byte_size": 10485760
  },
  "turnstile": { "required": false, "sitekey": null }
}

Render consent.disclosure_html as the label of a checkbox that starts unchecked. It’s your own consent text — edit it under Hiring → Settings → Consent, together with retention_months, which controls when Kit anonymizes entries nobody renewed.

Join the talent pool

POST /api/public/v1/talent_pool/entries
{
  "talent_pool_entry": {
    "email": "[email protected]",
    "linkedin_url": "https://linkedin.com/in/ada",
    "resume_signed_id": "eyJf…",
    "consent": true,
    "consent_ip_address": "203.0.113.7"
  },
  "turnstile_token": "<token>"
}

Returns 201 with a PII-free confirmation:

{ "id": "tpe_9fQ…", "status": "pending_verification", "submitted_at": "2026-06-11T09:30:00Z" }

CVs use the same presigned upload as applications — request a signed_id, PUT the bytes, then pass it as resume_signed_id.

Recording who consented

Kit stores a consent receipt with every entry: the exact text shown, the timestamp, and the IP address of the person who accepted. That last field is where server-side integrations quietly go wrong.

Submitting from a browser with a pk_ key, Kit observes the IP itself and ignores any consent_ip_address you send — a key that ships in page JavaScript must not be able to write its own receipt.

Submitting from your server with an sk_ key, the IP Kit sees is your server’s, not the applicant’s. Send the real one as consent_ip_address — in a Vercel Server Action, that’s the first hop of x-forwarded-for:

import { headers } from "next/headers";

const forwarded = (await headers()).get("x-forwarded-for");
const consentIp = forwarded?.split(",")[0]?.trim();

This value is asserted by you, not proven: Kit stores what you send once it parses as an IP address, and rejects anything else with 422 invalid_consent_ip. Omit it if you genuinely don’t know — Kit then records no IP, which is an honest gap rather than a receipt naming the wrong machine.

Errors

Errors return a consistent envelope:

{ "error": { "code": "validation_failed", "message": "Email can't be blank", "fields": { "email": ["can't be blank"] } } }

Status	Code	Meaning
401	invalid_key	Missing or invalid API key
403	bot_protection_required	Publishable (pk_) key has no origin allowlist or Turnstile configured
403	origin_not_allowed	Browser origin not in the key’s allowlist
404	not_found	Job not found or not published
409	already_applied	This email already applied to this job
409	already_in_talent_pool	This email is already in the talent pool
422	validation_failed	Invalid application fields — including a missing required resume or an unanswered required field or question (see fields)
422	consent_required	Talent-pool signup arrived without an accepted consent checkbox
422	invalid_consent_ip	consent_ip_address is not a valid IP address
422	turnstile_failed	Turnstile verification failed
422	invalid_content_type / file_too_large / invalid_byte_size	Rejected resume upload

Status Updates via Webhooks

To track applications after submission, configure outbound webhooks. Relevant events include application.submitted, application.advanced, and application.rejected, plus job_posting.published/paused/closed. Application payloads include both the numeric id and the API prefix_id (app_…), and the job’s public_token, so you can correlate webhook events with API records.

SDK & Next.js Template

Two official, open-source starting points sit on top of the REST contract above — use either, or skip both and call the endpoints directly with any HTTP client.

• TypeScript SDK — @startupkit-app/jobs. A typed, zero-dependency client (native fetch, ESM + CJS, Node ≥ 18.17) that runs in Node, browsers, and edge runtimes. Install with npm install @startupkit-app/jobs, then:

  import { createClient } from "@startupkit-app/jobs";
  
  const kit = createClient({ secretKey: process.env.KIT_SECRET_KEY });
  
  const page = await kit.listJobs({ department: "Engineering", remote: true });
  const job = await kit.getJob(page.data[0].id);
  const { signed_id } = await kit.uploadFile(resumeFile);
  await kit.apply(job.id, { email: "[email protected]", resume_signed_id: signed_id });
  

  Pass publishableKey (pk_…) instead of secretKey in browser code. Other methods: allJobs() async-iterates every page, createUpload() gives lower-level control over the presigned upload, and getTalentPool() / joinTalentPool() cover the talent-pool intake above. Non-2xx responses throw KitApiError (with .code and .fields); failures that never reach the API throw KitNetworkError. The client defaults to the https://app.startupkit.app base URL; pass baseUrl to override it for a custom career domain.

• Next.js template — nextjs-job-board. A production-ready careers site (Next.js App Router, Server Components + Server Actions, ISR with tag-based revalidation) you can fork or one-click deploy. It renders the application form dynamically from the API schema, does direct-to-storage presigned resume uploads, emits schema.org JobPosting JSON-LD (Google for Jobs ready), and optionally revalidates instantly via webhooks. Set one environment variable — STARTUPKIT_SECRET_KEY (your sk_… key) — and deploy:

  

  Live demo: nextjs-job-board-orcin.vercel.app. Optional environment variables: STARTUPKIT_BASE_URL (defaults to https://app.startupkit.app), NEXT_PUBLIC_TURNSTILE_SITE_KEY, REVALIDATE_SECRET, and NEXT_PUBLIC_COMPANY_NAME.

Both consume the contract above, so you can also build against any framework using plain HTTP. A typical custom job site wires up four calls: list jobs, fetch a job with its form, request a presigned upload for the resume, and submit the application. Because these are plain JSON over HTTPS, the same integration works from a server (sk_ key) or the browser (pk_ key with a bot defence configured).

Rate Limits

Application submissions are limited to 10/hour per IP and upload requests to 30/hour per IP and 300/hour per key, alongside the global API rate limits. Browser keys are additionally protected by their origin allowlist and optional Turnstile.

Talent-pool signups are limited to 100/hour per key. Browser (pk_) signups carry an additional 5/hour per IP; server (sk_) signups don’t, since every one of them reaches Kit from the same egress address and a per-IP ceiling would cap your whole site rather than one person.