Connector API guide

What this is

The connector API lets a tool you run — like a browser extension on a job board, or a script on your laptop — push applicants straight into a job. It feeds the same parse-and-score pipeline as the web upload, so imported candidates appear alongside manual ones and get scored by your own criteria.

You keep your job-board login. ShortlistKit never asks for or stores job-board passwords. A connector key can only add candidates; it cannot read, edit or delete anything.

1. Create a connector key

Go to Settings and open the Connectors section. Name the key (for example "Naukri extension") and click Create key.

Copy the key immediately — it starts with skc_ and will not be shown again. Treat it like a password; revoke it any time from the same page.

2. List your open jobs

Send your key as a bearer token. The response lists every open job with its ID, so your connector can pick a target without you copying UUIDs.

Example

curl https://www.shortlistkit.com/api/v1/import/jobs \
  -H "Authorization: Bearer ***"

Response: {"jobs": [{"id": "<uuid>", "title": "Backend Engineer", "status": "open"}]}

3. Import a candidate

POST to /api/v1/import as multipart form data. job_ref and resume are required; the rest are optional extras your connector can attach.

Fields

• job_ref — the job UUID (from the jobs list above)
• resume — the CV file: PDF or Word (.docx), up to 10 MB
• source — free-text label for where it came from, e.g. naukri (max 40 chars)
• source_url — the candidate's profile URL on the job board, if you have one
• name, email, phone — identity fields from the job board, used when the CV itself doesn't carry them

Example

curl -X POST https://www.shortlistkit.com/api/v1/import \
  -H "Authorization: Bearer ***" \
  -F job_ref=<uuid> -F resume=@resume.pdf \
  -F source=naukri -F "name=Asha Patil" -F email=asha@example.com

A new candidate returns 201 {"status":"created","queued":true}. Re-sending the same CV returns 200 {"status":"duplicate"} — imports are safely re-runnable, no double entries.

Limits and answers

• 30 imports per minute per key (a burst of duplicates still counts; the server dedupes).
• 401 invalid key · 403 key revoked or workspace not open (demo / pending approval) · 404 unknown job · 409 job closed · 422 bad file or field · 429 rate limit (retry after the Retry-After header).
• Every import is written to the job's audit trail with the key's fingerprint and the source you send.