> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talentunveiled.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Restart or retake the interview

> A pending or absent session is (re)started (crash recovery, does not consume a retake); a finished session that can be retaken is retaken; a finished session at its retake limit returns 409; a running session is a 202 no-op. Accepts an Idempotency-Key header.



## OpenAPI

````yaml /swagger/v2_schema.yaml post /applications/{application_id}/interview/retry
openapi: 3.0.3
info:
  title: TalentUnveiled API v2
  version: 2.0.0
  description: >-
    Public API v2 for managing jobs, applications, interviews, and webhooks.


    **Pagination:** list endpoints return a `{count, next, previous, results}`
    envelope. Page with the `limit` and `offset` query parameters; `limit`
    defaults to 50 and is capped at 200.
servers:
  - url: https://api.talentunveiled.com/api/v2
    description: Production server
security: []
tags:
  - name: Meta
    description: Identify the organization an API key belongs to.
  - name: Jobs
    description: Create, read, update, and archive job postings.
  - name: Applications
    description: Create applications and track them through the pipeline.
  - name: Interview Configuration
    description: The interview config and call schedule for a job.
  - name: Interview Criteria
    description: Evaluation criteria for a job's interview.
  - name: Interview Questions
    description: Questions asked during a job's interview.
  - name: Interview Results
    description: The scored interview result for an application.
  - name: Interview Calls
    description: Call attempts, scheduling, and transcripts.
  - name: CV Evaluations
    description: AI scoring of a candidate's CV against the job.
  - name: Insights
    description: Combined CV and interview insights for an application.
  - name: Webhooks
    description: Manage webhook subscriptions and inspect deliveries.
  - name: Hiring Team
    description: Manage the hiring team assigned to a job posting.
  - name: Members
    description: List the members of the organization.
paths:
  /applications/{application_id}/interview/retry:
    post:
      tags:
        - Interview Results
      summary: Restart or retake the interview
      description: >-
        A pending or absent session is (re)started (crash recovery, does not
        consume a retake); a finished session that can be retaken is retaken; a
        finished session at its retake limit returns 409; a running session is a
        202 no-op. Accepts an Idempotency-Key header.
      operationId: applications_interview_retry_create
      parameters:
        - in: header
          name: Idempotency-Key
          schema:
            type: string
          description: >-
            Unique key (e.g. a UUID v4) that makes this POST safe to retry: a
            repeated key replays the original response instead of creating a
            second resource.
        - in: path
          name: application_id
          schema:
            type: string
            format: uuid
          required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InterviewSession'
          description: Interview (re)started or in-flight.
        '401':
          description: Authentication credentials were not provided or are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The requested resource does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The interview is at its retake limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - apiKeyAuth: []
components:
  schemas:
    InterviewSession:
      type: object
      description: Session envelope + nested result. ``result`` is null until completed.
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        status:
          allOf:
            - $ref: '#/components/schemas/InterviewSessionStatusEnum'
          description: >-
            Current status of the interview session, which determines next steps
            in the interview process.


            * `pending` - Pending

            * `scheduled` - Scheduled

            * `in_progress` - In Progress

            * `rescheduled` - Rescheduled

            * `retry_scheduled` - Retry Scheduled

            * `completed` - Completed

            * `opted_out` - Opted Out

            * `unreachable` - Unreachable

            * `language_barrier` - Language Barrier

            * `failed` - Failed

            * `cancelled` - Cancelled
        is_terminal:
          type: boolean
          readOnly: true
        mode:
          allOf:
            - $ref: '#/components/schemas/InterviewModeEnum'
          description: |-
            Snapshot of the interview config mode at session creation time.

            * `web` - Web
            * `phone` - Phone
        language:
          allOf:
            - $ref: '#/components/schemas/LanguageEnum'
          description: |-
            Language of the interview session.

            * `en-US` - English
            * `de-DE` - German
        scheduled_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            [Scheduling enabled only] Scheduled date and time for the interview.
            Populated only when the interview config's scheduling is enabled.
            Null otherwise.
        retake_number:
          type: integer
          maximum: 2147483647
          minimum: 0
          description: Number of retakes. 0 = original attempt, 1 = first retake.
        call_retry_count:
          type: integer
          maximum: 2147483647
          minimum: 0
          description: >-
            Number of call retry attempts within the current retake. Reset on
            each retake.
        status_updated_at:
          type: string
          format: date-time
          description: >-
            Timestamp of the last update to the interview session status.
            Updated each time the status changes.
        error_message:
          type: string
          nullable: true
          description: Error details when the session fails or is unreachable.
        result:
          allOf:
            - $ref: '#/components/schemas/InterviewResult'
          nullable: true
          readOnly: true
      required:
        - id
        - is_terminal
        - language
        - mode
        - result
    ErrorResponse:
      type: array
      description: List of errors
      items:
        $ref: '#/components/schemas/ErrorItem'
    InterviewSessionStatusEnum:
      enum:
        - pending
        - scheduled
        - in_progress
        - rescheduled
        - retry_scheduled
        - completed
        - opted_out
        - unreachable
        - language_barrier
        - failed
        - cancelled
      type: string
      description: |-
        * `pending` - Pending
        * `scheduled` - Scheduled
        * `in_progress` - In Progress
        * `rescheduled` - Rescheduled
        * `retry_scheduled` - Retry Scheduled
        * `completed` - Completed
        * `opted_out` - Opted Out
        * `unreachable` - Unreachable
        * `language_barrier` - Language Barrier
        * `failed` - Failed
        * `cancelled` - Cancelled
    InterviewModeEnum:
      enum:
        - web
        - phone
      type: string
      description: |-
        * `web` - Web
        * `phone` - Phone
    LanguageEnum:
      enum:
        - en-US
        - de-DE
      type: string
      description: |-
        * `en-US` - English
        * `de-DE` - German
    InterviewResult:
      type: object
      description: The scored result body. Null on the session until ``status==completed``.
      properties:
        status:
          allOf:
            - $ref: '#/components/schemas/InterviewSessionResultStatusEnum'
          description: |-
            Current processing status of the interview result.

            * `pending` - Pending
            * `processing` - Processing
            * `completed` - Completed
            * `failed` - Failed
        scored_at:
          type: string
          format: date-time
          readOnly: true
        overall_score:
          type: string
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
          nullable: true
          description: >-
            Overall score for the interview session (1-5): the weighted average
            of scored competencies (score x weight) and scored optional
            qualifications (passed=5, failed=1), lowered for each failed
            required criterion. Null when too few criteria were scored to grade,
            or when every scored item has zero weight.
        overall_score_reasoning:
          type: string
          nullable: true
          description: Detailed reasoning behind the overall score.
        is_eligible:
          type: boolean
          description: >-
            False when the candidate failed a required criterion (a required
            qualification answered no, or a required competency scored below its
            minimum_score). The competency score is still computed; this flag is
            the gate. The specific failing criteria are derived on read from the
            criteria results.
        ineligibility_reasons:
          type: array
          items:
            $ref: '#/components/schemas/IneligibilityReason'
          readOnly: true
        summary:
          type: string
          nullable: true
          description: A concise summary of the candidate's performance in the interview.
        candidate_background:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            Key facts about the candidate's background extracted from the
            interview (e.g., years of experience, education).
        candidate_logistical_considerations:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            Logistical factors mentioned by the candidate (e.g., availability,
            relocation, notice period).
        candidate_motivation_and_interest:
          type: array
          items:
            type: string
          nullable: true
          description: Signals of the candidate's motivation and interest in the role.
        candidate_tools_and_skills:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            Technical skills, tools, and competencies identified from the
            interview.
        candidate_questions:
          type: array
          items:
            type: string
          nullable: true
          description: Questions the candidate asked during the interview.
        follow_up_questions:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            Suggested follow-up questions for the hiring team based on the
            interview.
        strengths:
          type: array
          items:
            type: string
          nullable: true
          description: Key strengths identified from the interview.
        weaknesses:
          type: array
          items:
            type: string
          nullable: true
          description: >-
            Key weaknesses and areas for improvement identified from the
            interview.
        red_flags:
          type: array
          items:
            type: string
          nullable: true
          description: Concerns or red flags identified from the interview.
        criteria_results:
          type: array
          items:
            $ref: '#/components/schemas/InterviewCriteriaResult'
          readOnly: true
        questions:
          type: array
          items:
            $ref: '#/components/schemas/V2InterviewQuestionResult'
          readOnly: true
      required:
        - criteria_results
        - ineligibility_reasons
        - questions
        - scored_at
    ErrorItem:
      type: object
      description: Individual error item
      properties:
        code:
          allOf:
            - $ref: '#/components/schemas/ErrorCodeEnum'
          description: Machine-readable error code
        detail:
          type: string
          description: Human-readable error message
        attr:
          type: string
          nullable: true
          description: Field name this error relates to (for validation errors)
      required:
        - code
        - detail
    InterviewSessionResultStatusEnum:
      enum:
        - pending
        - processing
        - completed
        - failed
      type: string
      description: |-
        * `pending` - Pending
        * `processing` - Processing
        * `completed` - Completed
        * `failed` - Failed
    IneligibilityReason:
      type: object
      properties:
        criteria_id:
          type: string
          format: uuid
          nullable: true
        name:
          type: string
        kind:
          allOf:
            - $ref: '#/components/schemas/CriterionKindEnum'
          nullable: true
        reason:
          type: string
      required:
        - criteria_id
        - kind
        - name
        - reason
    InterviewCriteriaResult:
      type: object
      description: >-
        One scored criterion. When the underlying criterion was later deleted,

        ``name``/``kind``/``is_required``/``minimum_score`` reflect the values
        captured

        at evaluation time and ``criteria_id`` is null.
      properties:
        criteria_id:
          type: string
          format: uuid
          nullable: true
        name:
          type: string
        kind:
          allOf:
            - $ref: '#/components/schemas/CriterionKindEnum'
          nullable: true
        is_required:
          type: boolean
        outcome:
          allOf:
            - $ref: '#/components/schemas/OutcomeEnum'
          description: >-
            scored: the criterion was evaluated. not_assessed: the transcript
            lacked sufficient evidence; not_assessed_reason explains why.


            * `scored` - Scored

            * `not_assessed` - Not assessed
        score:
          type: integer
          maximum: 2147483647
          minimum: 0
          nullable: true
          description: >-
            Competency: 1-5 BARS level. Qualification: null (use `passed`
            instead). Null when outcome=not_assessed.
        passed:
          type: boolean
          nullable: true
          description: >-
            [Qualification only] Pass/fail outcome against the bar stated in the
            criteria description. Populated only when outcome=scored. Null
            otherwise.
        minimum_score:
          type: integer
          nullable: true
        weight:
          type: string
          format: decimal
          pattern: ^-?\d{0,3}(?:\.\d{0,2})?$
          description: >-
            [Competency only] Snapshot of criteria.weight at time of scoring
            (preserves historical calculation).
        weighted_score:
          type: string
          format: decimal
          pattern: ^-?\d{0,8}(?:\.\d{0,2})?$
          readOnly: true
          nullable: true
        extracted_fact:
          type: string
          nullable: true
          description: >-
            [Qualification only] The fact the candidate stated that was
            evaluated against the bar named in criteria.description (e.g.
            'Licensed RN in California since 2019'). Populated only when
            outcome=scored. Empty otherwise.
        not_assessed_reason:
          type: string
          nullable: true
          description: >-
            Why this criterion could not be assessed (e.g. candidate gave a
            short/evasive answer, topic not covered, off-topic response).
            Required when outcome=not_assessed; must be empty when
            outcome=scored.
        reasoning:
          type: string
          description: One-sentence justification for the outcome, per the V3 methodology.
        highlights:
          type: array
          items:
            $ref: '#/components/schemas/InterviewHighlight'
      required:
        - criteria_id
        - highlights
        - is_required
        - kind
        - minimum_score
        - name
        - outcome
        - reasoning
        - weighted_score
    V2InterviewQuestionResult:
      type: object
      properties:
        sequence_number:
          type: integer
          maximum: 2147483647
          minimum: 0
          description: Snapshot of the question's position in the interview.
        question_text:
          type: string
          description: Snapshot of the question text at the time of the interview.
        answer:
          type: string
          nullable: true
          description: The applicant's answer to the interview question.
        answer_summary:
          type: string
          nullable: true
          description: >-
            1-2 sentence third-person summary of the candidate's answer,
            generated alongside `answer` by the question-answer extractor. Null
            when the question was not meaningfully answered (mirrors `answer`).
      required:
        - question_text
        - sequence_number
    ErrorCodeEnum:
      type: string
      enum:
        - error
        - invalid_input
        - parse_error
        - authentication_failed
        - not_authenticated
        - permission_denied
        - not_found
        - method_not_allowed
        - not_acceptable
        - unsupported_media_type
        - throttled
        - required
        - does_not_exist
        - incorrect_type
        - no_match
        - incorrect_match
        - not_a_list
        - not_a_dict
        - empty
        - candidate_user_mismatch
        - candidate_not_found
        - cross_organization_application
        - already_exists
        - call_service_error
        - call_not_joinable
        - call_config_error
        - call_access_denied
        - call_already_linked
        - date_range_too_large
        - date_range_start_after_end
        - invalid_date
        - language_not_configured
        - vapi_api_error
        - webhook_processing_error
        - proxy_error
        - configuration_error
        - interview_call_already_processed
        - call_type_switch_error
        - slot_in_past
        - interview_not_scheduled
        - interview_opt_out_not_eligible
        - interview_retry_not_allowed
        - retake_limit_reached
        - interview_session_not_joinable
        - interview_session_retake_not_eligible
        - interview_session_already_processing
        - interview_session_not_completed
        - interview_session_reset_not_allowed
        - interview_mode_locked
        - application_already_exists
        - gateway_verification_failed
        - invalid_file_type
        - file_too_large
        - cv_already_exists
        - cv_required
        - custom_fields_too_large
        - nylas_grant_already_exists
        - nylas_upstream_error
        - otp_challenge_not_found
        - job_posting_not_found
        - job_application_not_found
        - workflow_execution_error
        - llm_generation_failed
        - report_generation_failed
        - interview_config_has_no_criteria
        - scheduling_not_enabled
        - interview_session_not_reschedulable
        - interview_version_mismatch
        - v3_job_missing_config
        - idempotency_key_conflict
        - idempotency_key_invalid
        - application_status_transition_invalid
        - application_state_conflict
        - external_id_conflict
        - qualification_cannot_have_score
        - competency_requires_bars
      description: Machine-readable error code
    CriterionKindEnum:
      enum:
        - competency
        - qualification
      type: string
      description: |-
        * `competency` - Competency
        * `qualification` - Qualification
    OutcomeEnum:
      enum:
        - scored
        - not_assessed
      type: string
      description: |-
        * `scored` - Scored
        * `not_assessed` - Not assessed
    InterviewHighlight:
      type: object
      description: Transcript evidence backing a scored criterion.
      properties:
        quote:
          type: string
        reasoning:
          type: string
          description: Why this quote is relevant to the criteria score.
        sentiment:
          $ref: '#/components/schemas/SentimentEnum'
        highlight_time_sec:
          type: string
          format: decimal
          pattern: ^-?\d{0,7}(?:\.\d{0,3})?$
          readOnly: true
          nullable: true
      required:
        - highlight_time_sec
        - quote
        - reasoning
    SentimentEnum:
      enum:
        - positive
        - negative
        - neutral
      type: string
      description: |-
        * `positive` - Positive
        * `negative` - Negative
        * `neutral` - Neutral
  securitySchemes:
    apiKeyAuth:
      type: http
      scheme: bearer
      description: >-
        API key authentication for the public API. Pass your API key as a Bearer
        token.

````