---
title: "Check interview session scheduling readiness"
method: GET
path: "/v1/interview_sessions/{interview_session_id}/actions/readiness"
tags: ["Scheduling"]
---

# Check interview session scheduling readiness

`GET /v1/interview_sessions/{interview_session_id}/actions/readiness`

## Request

- Base URL: `https://api.yardstick.team`
- URL: `https://api.yardstick.team/v1/interview_sessions/{interview_session_id}/actions/readiness`
- Auth: HTTP bearer

Check interview session scheduling readiness

**Required scopes:** `scheduling:read`

Read-only. Returns `{ ready: true }` when the session is schedulable, or a blocker envelope (`{ ready: false, blocker_code, blocker_message, blocker_metadata }`) identifying the recovery flow. Stable blocker codes cover interviewer assignment, provider setup, event-type mapping, and plan-lineage resolution: `INTERVIEWER_ASSIGNMENT_REQUIRED`, `INTERVIEWER_ASSIGNMENT_AMBIGUOUS`, `SCHEDULER_INTEGRATION_REQUIRED`, `SCHEDULER_WEBHOOK_SETUP_REQUIRED`, `SCHEDULER_EVENT_TYPE_MAPPING_MISSING`, `INTERVIEW_PLAN_NOT_FOUND`, `INTERVIEW_PLAN_AMBIGUOUS`, `INTERVIEW_PLAN_LINEAGE_MISMATCH`. When the mapping blocker fires, metadata may include the interview duration, mapping key, provider, integration id, assigned scheduler ids, and `settings_url` for `/admin/integrations/scheduling`; it does not include provider secrets. Plan-lineage blockers return safe application/job/session context, candidate plan counts, and plan source context without interview sequences or provider internals. Inherits the org-default rate limit applied by `withApi`; no `Idempotency-Key` semantics (idempotency keys are ignored on GET).

**Example (curl):**

```bash
curl https://api.yardstick.team/v1/interview_sessions/is_abc123/actions/readiness \
  -H 'Authorization: Bearer ys_sk_live_…'
```

**Example (TypeScript):**

```ts
await fetch(
  "https://api.yardstick.team/v1/interview_sessions/is_abc123/actions/readiness",
  { headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` } },
).then((r) => r.json());
```

## Path parameters

- `interview_session_id` string, required

## Headers

- `X-Request-Id` string

## Response `200`

Success

- union: Discriminated readiness response. `ready: true` carries no extra fields; `ready: false` carries a structured blocker envelope.
  - object: Session is ready to be scheduled.
    - `ready` true, required
  - object: Session is not ready; `blocker_code` identifies the recovery flow.
    - `blocker_code` 'INTERVIEWER_ASSIGNMENT_REQUIRED' | 'INTERVIEWER_ASSIGNMENT_AMBIGUOUS' | 'SCHEDULER_INTEGRATION_REQUIRED' | 'SCHEDULER_WEBHOOK_SETUP_REQUIRED' | 'SCHEDULER_EVENT_TYPE_MAPPING_MISSING' | 'INTERVIEW_PLAN_NOT_FOUND' | 'INTERVIEW_PLAN_AMBIGUOUS' | 'INTERVIEW_PLAN_LINEAGE_MISMATCH' | 'ROUND_ALREADY_SCHEDULED', required: Stable machine-readable blocker code.
    - `blocker_message` string, required: Human-readable explanation of the blocker.
    - `blocker_metadata` object, required: Free-form structured metadata describing the blocker. Shape varies by `blocker_code`: `INTERVIEWER_ASSIGNMENT_REQUIRED` → `{ interview_session_id }`; `INTERVIEWER_ASSIGNMENT_AMBIGUOUS` → `{ interview_session_id, candidate_count }`; `SCHEDULER_INTEGRATION_REQUIRED` → `{ interviewer_user_id }`; `SCHEDULER_WEBHOOK_SETUP_REQUIRED` → `{ interviewer_user_id, provider }`; `SCHEDULER_EVENT_TYPE_MAPPING_MISSING` → `{ interviewer_user_id, provider, integration_id, interview_duration_minutes, mapping_key, settings_url }`; `INTERVIEW_PLAN_NOT_FOUND` → safe application/job/session context; `INTERVIEW_PLAN_AMBIGUOUS` → safe application/job context and candidate plan count; `INTERVIEW_PLAN_LINEAGE_MISMATCH` → safe application/job context, plan source, and linked-plan job context; `ROUND_ALREADY_SCHEDULED` → `{ interview_session_id, interview_id, booking_status }`, returned when the round already holds a confirmed booking (`booked` or `rescheduled`). Cancel the existing booking first. Rounds that are unscheduled, cancelled, or already have an outstanding link (`link_sent`) are not blocked -- each call still generates a fresh scheduling link. Missing event-type mapping metadata is safe to show to operators and points the assigned interviewer to `/admin/integrations/scheduling`. Plan-lineage blockers do not include interview sequences, provider secrets, OAuth tokens, Vault ids, or raw provider payloads.
    - `ready` false, required

## Other responses

- `400`: Invalid request
- `401`: Authentication failure
- `403`: Permission denied (scope or feature flag)
- `404`: Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.
- `409`: Conflict (e.g. idempotency key reuse with different body)
- `429`: Rate limited
- `500`: Internal error

---

[API](https://skmtc.dev/yardstick/apis/yardstick-public-api.md) · [All operations](https://skmtc.dev/yardstick/apis/yardstick-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/yardstick/apis/yardstick-public-api/revisions/bef1d2eaaaa1?raw)