API reference/Opportunity pipeline/Interviews

POSTLive

Create interview

Schedules an interview for an application.

/v1/interviews

Authorization

Credential

oauth_user

Required scopes

applications:write

Request body

JSON · application/json

applicationIdstring

applicationobject

kindstringrequired

phone · video · technical · onsite · panel

scheduledAtnumberrequired

locationstring

interviewerContactIdsarray

Implementation note

Provide exactly one of `applicationId` (an existing application) or `application` (inline fallback: creates the application at stage interviewing — with a job carrying the title/company/sourceUrl — and the interview in one transaction, so a denial or failure writes nothing). Duplicate-safe: creating an interview whose (applicationId, kind, scheduledAt) exactly matches an existing scheduled interview returns that interview with 200 instead of inserting a second row (a capture retried from the browser extension must not double-book). A first create returns 201.

Error responses

400Invalid request

The request body was missing, malformed, or failed schema validation. Field-level problems are listed under `issues`.

401Authentication required

No valid credentials were supplied. Attach a Bearer access token and retry.

402Upgrade required

The authenticated user's plan does not include this capability. `feature` names the gated capability, `requiredPlan` the cheapest plan that unlocks it, `currentPlan` the user's plan today, and `upgradeUrl` links to checkout. This is a plan gate, not a transient error — retrying without upgrading fails again; surface `upgradeUrl` to the user instead. Dormant until a plan that grants the feature is active, so a route that documents it may not currently return it.

403Insufficient scope

The token is valid but lacks the OAuth scope (or token kind) this endpoint requires.

404Resource not found

The addressed resource does not exist, or is not visible to the caller.