Developers
API reference
REST under /api/v1. Authenticate with Bearer API keys on Growth and Scale plans. Machine-readable OpenAPI is always available at the JSON endpoint.
Base URL https://app.otter.diy/api/v1
Auth Authorization: Bearer <api_key>
Keys Create in Settings → API Keys. Each key is bound to one workspace, stored hashed, and shown once. No tenant header needed.
Spec: /api/v1/openapi.json · MCP install
/api/v1API root / capability discovery
/api/v1/jobsList jobs
Returns jobs for the authenticated tenant (DB-backed). Each job has `visibility` (public or internal) and `internal` (true for an Internal job: hidden from your careers page and job feeds). Requires Growth+. Each item has `custom_fields`: your workspace fields from Settings → Fields as { label: value } (null when empty). Fields marked “Salary access only” appear only when the key’s creator can see salaries.
/api/v1/jobs/{id}Get a job
Includes `stages`: this job's own pipeline, in order [{ id, name, category, position }]. Every job can name and order its stages differently; `category` is always one of applied, screening, interview, offer, hired, rejected, so you can compare jobs. Also includes `custom_fields`: your workspace fields from Settings → Fields as { label: value } (null when empty). Fields marked “Salary access only” appear only when the key’s creator can see salaries.
/api/v1/jobs/{id}Update a job
Change any of the listed fields; omit the rest. `description` accepts HTML (headings, lists, links) or plain text (blank lines become paragraphs). Pass `expected_updated_at` (from a previous GET) to get a 409 instead of overwriting someone else's change. Requires a read & write key. The change appears on the job's activity. With job approvals on, setting `status` to open answers 409 `approval_required` until the job is approved (POST /approvals); editing an approved job that isn't open yet resets its approval.
/api/v1/candidatesList or search candidates
Pass `q` for free-text search (name, email, headline, company). DB-backed. Requires Growth+. Each item has `custom_fields`: your workspace fields from Settings → Fields as { label: value } (null when empty). Fields marked “Salary access only” appear only when the key’s creator can see salaries.
/api/v1/candidatesCreate a candidate
Needs a read & write key. Body: `name` (or `first_name`/`last_name`) and/or `email`, plus optional `phone`, `headline`, `current_company`, `location`, `linkedin`, `tags`, `source_label` and `job_id` (adds them to that job's first stage). An email that already belongs to a candidate reuses that person (200, `linked_existing_candidate: true`) instead of creating a duplicate. Unknown fields are rejected. Supports Idempotency-Key.
/api/v1/candidates/{id}Get a candidate
Includes `custom_fields` (Settings → Fields) as { label: value }; “Salary access only” fields appear only when the key’s creator can see salaries.
/api/v1/candidates/{id}/emailsList a candidate's emails with delivery status
Email trail (no bodies), newest first. `status` is sent, delivered, read, replied, bounced, failed, held or received. Read ignores automatic opens by mail privacy features and security scanners; open tracking is never certain. Requires Growth+.
/api/v1/candidates/{id}/messagesList a candidate's SMS and WhatsApp messages
Messages in both directions, newest first, with `channel` (sms or whatsapp), `direction`, `body`, `status` (queued, sent, delivered, read, failed, undelivered, received), E.164 `from` / `to`, the approved `whatsapp_template` if one was used, and timestamps. Requires Growth+.
/api/v1/meWhich workspace this key belongs to
Used by Zapier and Make to test a connection. Returns { data: { workspace: { id, slug, name }, scopes } }.
/api/v1/webhooksList webhook subscriptions
/api/v1/webhooksSubscribe a URL to events (REST hooks)
Body: { url, events: [...] } (or `event`, `target_url`; optional `name`). Events: application.created, application.stage_changed, interview.scheduled, interview.rescheduled (`data.interview.previous_starts_at`/`previous_ends_at`), interview.cancelled, candidate.hired, candidate.rejected, message.sent, message.received (SMS / WhatsApp; `data.message` has id, channel, direction, status, body), referral.created (`data.referral` has id, referrer { name }, source, created_at; the referral note stays in Otter), approval.requested, approval.approved (also overrides), approval.rejected (`data.approval` has id, kind job|offer, offer_id, reason, mode, status, requested_by, decided_by, comment, override_reason, steps, url). Public https URLs only. Stage events carry `data.stage` { id, name, category }. Each delivery is a JSON POST with Otter-Event, Otter-Delivery and Otter-Signature: t=<unix>,v1=<hex HMAC-SHA256 of `t.rawBody`>. Failed deliveries retry for about 9 hours. Requires a write key.
/api/v1/webhooks/{id}Unsubscribe a webhook
/api/v1/applicationsList applications
Each item has `stage`: { id, name, category } (the job's own stage name plus its standard category). Filter with `job_id`.
/api/v1/applications/{id}Get an application
Includes `stage` ({ id, name, category }), `knockout_flagged` and `answers`: { cover_note, questions: [{ id, label, type, value, file, knockout_failed }] } from the careers application form. Knockout flags never reject anyone.
/api/v1/applications/{id}/moveMove an application to a stage
Needs a read & write key. Body: `stage_id` (a stage of the same job, from GET /jobs/{id}), optional `rejection_reason_id` (required for rejected stages when your workspace requires reasons; the error lists valid ids) and `skip_automations`. Stage checks are enforced (409 `stage_checks` with what is missing). Stage automations and webhooks run as for a move in the app. Supports Idempotency-Key.
/api/v1/interviewsList interviews
Each item carries `stage_id` and `interview_kit` ({ id, name } or null): the kit picked when it was scheduled, else the stage's kit.
/api/v1/jobs/{id}/interview-kitsList a job's interview kits
Kits per stage, in order: `name`, `stage_id` / `stage_name`, `duration_minutes`, `purpose`, `questions` [{ id, text, what_good_looks_like, scorecard_skill_id }] and `scorecard` ({ source: kit | workspace, criteria [{ id, label, scale_max, guidance }], require_overall, require_notes }). Kits guide interviewers; nothing rejects or ranks candidates. Requires Growth+.
/api/v1/interview-kitsList reusable interview kit templates
Templates from Settings → Interview Kits, in the same shape as job kits (`is_template: true`). Requires Growth+.
/api/v1/notesList notes
/api/v1/notesCreate a note
Attach a note to a candidate (optionally tied to an application). Requires a read & write key. The note is authored by the key's creator and appears on the candidate timeline.
/api/v1/referralsList employee referrals
Newest first. Each item has `referrer` ({ user_id, name }), `note`, `source` (member, link or api) and a coarse `status`: in_review, interviewing, hired or not_selected.
/api/v1/referralsRefer someone to a job
Refer a person to an open job (public or Internal). Requires a read & write key. If a candidate with that email already exists they are linked, not duplicated, and added to the job if needed. The hiring team is notified in Otter; the person referred is never emailed. Fires the `referral.created` webhook.
/api/v1/referrals/{id}Get a referral
/api/v1/scheduling-linksList candidate scheduling links
Newest first. `status` is open, booked, cancelled or expired; `interview_id` is set once booked. The URL itself is only returned when a link is created.
/api/v1/scheduling-linksCreate a scheduling link
A private link for the candidate to pick their own time. Requires a read & write key. Offers only times inside every interviewer's working hours, clear of their Otter interviews (plus `buffer_minutes`) and, when calendar sync is connected, their calendar's busy times, between `starts_on` and `ends_on` (at most 30 days; the link expires after `ends_on`). Booking creates the interview with the application's stage and kit and fires `interview.scheduled`. The candidate can change (up to `max_reschedules`) or cancel up to `min_notice_hours` before. Otter doesn't send the link: put `url` in your email. Reschedule link: send `interview_id` (plus optional `starts_on`, `ends_on`, `buffer_minutes`, `min_notice_hours`, `max_reschedules`) instead; the panel, length, place and kit come from that interview, booking moves it in place and fires `interview.rescheduled`; an earlier unused reschedule link for the same interview is withdrawn. 409 if the interview was cancelled or already happened.
/api/v1/scheduling-links/{id}Get a scheduling link
/api/v1/scheduling-links/{id}/withdrawWithdraw an unused scheduling link
/api/v1/candidates/searchSmart search
Plain-language candidate search. `query` (e.g. "React developers in Pune with 5+ years", "ex-Flipkart product managers") is turned into filters, returned as `filters` so you can see and adjust them; `filters` you pass win over the query. Postgres full-text over profiles and resume text plus skills, titles, companies (current or past), location (Bangalore = Bengaluru…), years of experience, date added, stage, source, tag and job. Each item has `match.reasons` and a resume `match.snippet` with matched words in **bold**. Words about age, gender, religion or other personal traits are never used (`ignored`). Any key (read-only is fine).
/api/v1/candidates/searchSmart search (query string)
Same as POST with `q` as the plain-language query.
/api/v1/bulk-importsList bulk resume uploads
The 25 most recent, with counts (added, matched_existing, failed, in_progress).
/api/v1/bulk-importsUpload resumes in bulk
Up to 20 files per request (the request body must stay under ~4 MB, so use `url` for big files); up to 500 files per workspace per day. Read & write key. Each file is read in the background (AI under the workspace's daily cap, then without AI). Someone whose email or phone already exists gets the resume linked to their profile instead of a duplicate (`matched_existing`). New people get source `bulk_upload`. Target `job` adds everyone to the job's Applied stage, `pool` to a talent pool. Nobody is emailed and no 'applied' automations run. Returns 202; poll GET /bulk-imports/{id}. Supports Idempotency-Key.
/api/v1/bulk-imports/{id}Bulk upload progress
`summary` counts and each file's status (in_progress, added, matched_existing, failed with `error`) and the candidate it became.
/api/v1/bulk-imports/{id}/retryRetry failed files
Reads failed files again (uploaded copies are kept for a day). Read & write key.
/api/v1/job-descriptions/draftDraft a job post from a brief
Full post in the workspace's tone (Settings → Job Writer) plus suggested skills, knockout questions and interview rounds. Never saves. Pay and benefits appear only if given, verbatim. One AI use from the workspace's daily writer limit; without AI (or over the limit) returns a template filled from the brief (`by: template`).
/api/v1/job-descriptions/rewriteRewrite, shorten or expand a post
Keeps the facts; new pay or benefit lines are removed (`removed_blocks`). Never saves. One AI use. 429 when today's limit is used.
/api/v1/job-descriptions/checkInclusive-language check
Flags gender-coded, age, ability, background and exclusionary wording with why and suggestions. Free (no AI); never edits.
/api/v1/approvalsList approval requests
Newest first. Approvals are optional (Settings → Approvals): jobs need approval to open (and optionally to reopen), offer letters to be sent for e-signature. `steps` is the approver chain, each with status waiting, pending, approved, rejected or skipped.
/api/v1/approvalsRequest approval
Ask the workspace's approval chain to approve opening (or reopening) a job, or sending an offer letter. Requires a read & write key; attributed to the key's creator. A job opens by itself once approved. Returns the waiting request (200) if there already is one. 409 when approvals are off, the job/offer doesn't need approval, or nobody could complete the chain (e.g. the job has no hiring manager).
/api/v1/approvals/{id}Get an approval request
With its steps and the audit log (`events`: requested, step_approved, approved, rejected, overridden, reset, cancelled, used).
/api/v1/approvals/{id}/{action}Approve, reject or override
Decides as the API key's creator, who must be an approver for the current step and not the requester. `reject` needs `comment`; `override` (owners only) needs `reason`, approves straight away and is kept in the audit log. Requires a read & write key.
/api/v1/automationsList automations
Built-in automations (id may be null until edited; address them by `system_key`) and your team's automations, with on/off state and a plain-language summary.
/api/v1/automations/{id}Get an automation
/api/v1/automations/{id}Switch an automation on or off
Only `enabled` can be changed through the API; steps are edited in Settings → Automations. An unfinished automation can't be switched on (422). `hired_close` is always on. Requires a read & write key; recorded in the audit log.
/api/v1/automations/{id}/runsAutomation run log
Newest first: when, which candidate, result (scheduled, succeeded, partial, failed, skipped, cancelled), each step's outcome and any error.
Errors
Errors return { "error": string, "code": string } with HTTP status 400 / 401 / 403 / 404 / 409 / 422 / 429 / 503. List responses use { data: { items, next_cursor, meta } }.
Paging
Pass limit (1 to 100, default 25) and the opaque next_cursor from the previous page as cursor. A malformed cursor returns 400.
Rate limits
Each key can make 600 requests per minute. Above that you get 429 with a Retry-After header in seconds.
Safe retries
Send an Idempotency-Key header (up to 255 letters, digits, - _ : .) on POST requests. Repeating the same request with the same key within 24 hours returns the original response with Idempotent-Replayed: true instead of creating a duplicate. Reusing a key with a different body returns 422.