openapi: 3.0.3
info:
  title: Willo Integration API V2 Child Organisations Interviews API
  description: 'The Willo Integration API V2 exposes the actions that can be carried out in the Willo asynchronous ("one-way") video interviewing platform as a public REST API, so you can add video interviewing to a job board, ATS, CRM, or staffing platform. Resources include Departments (called "Companies" in the UI), Interviews (the set of pre-defined questions a participant answers - typically a "job" in an ATS), Participants (candidates - no login or app required), their video Responses and identity-verification media, Message Templates (invite/reminder/success email and SMS), Users, Webhooks, Interview Templates, and Child Organisations. Authentication is by API key ("integration key") passed in the Authorization header; each user has their own key from the Willo Integrations page. All requests must be made over HTTPS.

    Endpoint paths, HTTP methods, authentication, status codes, webhook triggers, and the two host environments below are confirmed from Willo''s published Postman API reference. Request and response body schemas are modeled from the documented resource glossary and are illustrative; confirm exact field names and shapes against the live Willo reference before production use.'
  version: '2.0'
  contact:
    name: Willo
    url: https://www.willo.video/api
  termsOfService: https://www.willo.video/terms
servers:
- url: https://api.willotalent.com/api/integrations/v2
  description: Production
- url: https://api.stage.willotalent.com/api/integrations/v2
  description: Staging
security:
- apiKeyAuth: []
tags:
- name: Interviews
  description: A named set of pre-defined questions a participant answers; typically a "job" in an ATS.
paths:
  /interviews/:
    get:
      operationId: listInterviews
      tags:
      - Interviews
      summary: List Interviews
      description: Lists interviews (jobs) accessible to the API key.
      responses:
        '200':
          description: A list of interviews.
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Interview'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createInterview
      tags:
      - Interviews
      summary: Create Interview
      description: Creates an interview with a list of pre-defined questions.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InterviewInput'
      responses:
        '201':
          description: The created interview.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Interview'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /interviews/{key}/:
    parameters:
    - $ref: '#/components/parameters/Key'
    get:
      operationId: getInterview
      tags:
      - Interviews
      summary: Interview Details
      description: Retrieves a single interview, including its questions.
      responses:
        '200':
          description: The requested interview.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Interview'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: replaceInterview
      tags:
      - Interviews
      summary: Update Interview (PUT)
      description: Fully replaces an interview.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InterviewInput'
      responses:
        '200':
          description: The updated interview.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Interview'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateInterview
      tags:
      - Interviews
      summary: Update Interview (PATCH)
      description: Partially updates an interview.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InterviewInput'
      responses:
        '200':
          description: The updated interview.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Interview'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteInterview
      tags:
      - Interviews
      summary: Delete Interview
      description: Deletes an interview.
      responses:
        '204':
          description: The interview was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    NotFound:
      description: The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: No valid API key was provided.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request was unacceptable, often due to a missing required parameter.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Question:
      type: object
      description: A single pre-defined question within an interview.
      properties:
        prompt:
          type: string
        type:
          type: string
          description: Answer type, for example video, audio, or text.
        max_duration:
          type: integer
          description: Maximum answer duration in seconds.
        max_retakes:
          type: integer
        thinking_time:
          type: integer
          description: Thinking time in seconds before recording starts.
    Error:
      type: object
      properties:
        detail:
          type: string
    Interview:
      type: object
      description: A named set of pre-defined questions; typically a "job" in an ATS.
      properties:
        key:
          type: string
        title:
          type: string
        department:
          type: string
          description: Key of the department the interview belongs to.
        language:
          type: string
        questions:
          type: array
          items:
            $ref: '#/components/schemas/Question'
        created:
          type: string
          format: date-time
    InterviewInput:
      type: object
      required:
      - title
      properties:
        title:
          type: string
        department:
          type: string
        language:
          type: string
        questions:
          type: array
          items:
            $ref: '#/components/schemas/Question'
  parameters:
    Key:
      name: key
      in: path
      required: true
      description: The unique key of the resource.
      schema:
        type: string
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: The integration key ("API key") available on the Willo Integrations page at https://app.willotalent.com/integrations, sent in the Authorization header. Each user has their own key carrying that user's permissions.