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

# Add an interview to an application

> Adds an interview to an application. `type` decides the meeting of the interview: `withoutMeeting` logs an interview that was planned in another tool, `existingMeeting` links a meeting that already exists. Neither creates a calendar event or sends an invitation. `kind` says who is in the interview: the client, or only a user of your organization. The interview gets the assigned team of the application unless `teamId` is sent.



## OpenAPI

````yaml /api-reference/openapi.json post /applications/{id}/interviews
openapi: 3.1.0
info:
  title: Spott API Reference
  version: '0.1'
servers:
  - url: https://api.gospott.com
security: []
tags: []
paths:
  /applications/{id}/interviews:
    post:
      tags:
        - Interviews
      summary: Add an interview to an application
      description: >-
        Adds an interview to an application. `type` decides the meeting of the
        interview: `withoutMeeting` logs an interview that was planned in
        another tool, `existingMeeting` links a meeting that already exists.
        Neither creates a calendar event or sends an invitation. `kind` says who
        is in the interview: the client, or only a user of your organization.
        The interview gets the assigned team of the application unless `teamId`
        is sent.
      operationId: createInterviewForApplication
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateInterviewDto'
      responses:
        '201':
          description: The interview was created. Returns its id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateRecordResponseDto'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '400':
          description: >-
            Bad request - the interview does not match its `type`:
            `withoutMeeting` requires `startTime` and `endTime` and does not
            accept `meetingId`, `existingMeeting` requires `meetingId` and does
            not accept `startTime`, `endTime` or `title`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseDto'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '401':
          description: Unauthorized - invalid or missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseDto'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '404':
          description: The application, the meeting or the team does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseDto'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '409':
          description: The meeting is already the interview of an application.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseDto'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '429':
          description: >-
            Too Many Requests. The published limit for this endpoint is 600
            requests per minute per workspace. The limit in force for your
            workspace can differ from it in either direction — a workspace on a
            free trial can be capped lower, and a higher limit can be arranged
            through support — so the headers, not this number, are
            authoritative. Read the RateLimit-Policy response header for the
            quota actually in force and RateLimit for what is left of the
            current window; on a 429, Retry-After gives the seconds to wait.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExceptionBaseDto'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
        '500':
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorDto'
          headers:
            RateLimit:
              $ref: '#/components/headers/RateLimit'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
      security:
        - x-api-key: []
components:
  schemas:
    CreateInterviewDto:
      type: object
      properties:
        interview:
          $ref: '#/components/schemas/CreateInterviewInnerDto'
        teamId:
          description: >-
            The assigned team of the interview. Leave it out to use the assigned
            team of the application. Send `null` for no team.
          anyOf:
            - type: string
              minLength: 1
            - type: 'null'
      required:
        - interview
      additionalProperties: false
    CreateRecordResponseDto:
      type: object
      properties:
        id:
          type: string
          minLength: 1
      required:
        - id
    ExceptionBaseDto:
      type: object
      properties:
        status:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        category:
          $ref: '#/components/schemas/ApiErrorCategoryDto'
        message:
          type: string
        requestId:
          type: string
      required:
        - status
        - message
        - requestId
    InternalServerErrorDto:
      type: object
      properties:
        status:
          type: number
          const: 500
        category:
          type: string
          enum:
            - INTERNAL_ERROR
        message:
          type: string
          enum:
            - Internal server error
        requestId:
          type: string
      required:
        - status
        - category
        - message
        - requestId
    CreateInterviewInnerDto:
      oneOf:
        - $ref: '#/components/schemas/CreateInterviewWithoutMeetingDto'
        - $ref: '#/components/schemas/CreateInterviewWithExistingMeetingDto'
    ApiErrorCategoryDto:
      type: string
      enum:
        - MALFORMED_REQUEST
        - SCHEMA_VALIDATION_FAILED
        - DOMAIN_VALIDATION_FAILED
        - OPERATION_LIMIT_EXCEEDED
        - AUTHENTICATION_REQUIRED
        - AUTHENTICATION_FAILED
        - SECURITY_CHALLENGE_REQUIRED
        - SECURITY_CHALLENGE_FAILED
        - PERMISSION_DENIED
        - ENTITLEMENT_REQUIRED
        - PROVIDER_AUTHENTICATION_REQUIRED
        - PROVIDER_AUTHENTICATION_FAILED
        - CONFIGURATION_REQUIRED
        - RESOURCE_NOT_FOUND
        - RESOURCE_ALREADY_EXISTS
        - RESOURCE_EXPIRED
        - RESOURCE_BUSY
        - RESOURCE_STATE_CONFLICT
        - QUOTA_EXCEEDED
        - RATE_LIMITED
        - UNSUPPORTED_OPERATION
        - UPSTREAM_REJECTED
        - TIMEOUT
        - TEMPORARILY_UNAVAILABLE
        - INTERNAL_ERROR
    CreateInterviewWithoutMeetingDto:
      type: object
      properties:
        type:
          type: string
          enum:
            - withoutMeeting
          description: Logs an interview that has no meeting. Creates no calendar event.
        startTime:
          $ref: '#/components/schemas/DateISO'
          description: Moment the interview starts.
          example: '2026-08-12T08:30:00.000Z'
        endTime:
          $ref: '#/components/schemas/DateISO'
          description: Moment the interview ends.
          example: '2026-08-12T09:15:00.000Z'
        title:
          description: Title of the interview.
          example: Interview with the hiring manager
          anyOf:
            - type: string
              minLength: 1
              maxLength: 255
            - type: 'null'
        kind:
          $ref: '#/components/schemas/InterviewKind'
          description: >-
            Who is in the interview. `CANDIDATE_WITH_CLIENT`: the client is in
            the interview, a user of your organization may also be present.
            `CANDIDATE_WITH_USER`: only a user of your organization is with the
            candidate.
      required:
        - type
        - startTime
        - endTime
        - kind
      additionalProperties: false
    CreateInterviewWithExistingMeetingDto:
      type: object
      properties:
        type:
          type: string
          enum:
            - existingMeeting
          description: >-
            Makes a meeting that already exists the interview of the
            application.
        meetingId:
          type: string
          minLength: 1
          description: >-
            Identifier of the meeting. The interview takes its start time, end
            time and title from the meeting. A meeting can be the interview of
            one application only.
        kind:
          $ref: '#/components/schemas/InterviewKind'
          description: >-
            Who is in the interview. `CANDIDATE_WITH_CLIENT`: the client is in
            the interview, a user of your organization may also be present.
            `CANDIDATE_WITH_USER`: only a user of your organization is with the
            candidate.
      required:
        - type
        - meetingId
        - kind
      additionalProperties: false
    DateISO:
      format: date-time
      anyOf:
        - type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
        - type: string
          format: date
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
    InterviewKind:
      type: string
      enum:
        - CANDIDATE_WITH_CLIENT
        - CANDIDATE_WITH_USER
  headers:
    RateLimit:
      description: >-
        Quota state for this endpoint, as an RFC 8941 structured field
        (draft-ietf-httpapi-ratelimit-headers). The quoted value names the
        policy — the operationId of the endpoint the counters belong to. `r` is
        how many requests are left in the current window, `t` how many seconds
        remain before it resets.
      schema:
        type: string
      example: '"getCandidates";r=417;t=23'
    RateLimit-Policy:
      description: >-
        The policy the RateLimit header reports against, as an RFC 8941
        structured field. `q` is the quota — the requests allowed per window —
        and `w` the window length in seconds. Limits are per endpoint, so the
        quota differs between operations. This is the quota in force for the
        calling workspace, which can be lower or higher than the default
        published on the operation; treat it as authoritative.
      schema:
        type: string
      example: '"getCandidates";q=600;w=60'
    Retry-After:
      description: >-
        Seconds to wait before retrying. Sent on 429 responses; it matches the
        `t` parameter of the RateLimit header.
      schema:
        type: integer
      example: 23
  securitySchemes:
    x-api-key:
      type: apiKey
      name: x-api-key
      in: header
      description: >-
        API key for authentication. Get your API key from Settings → API Keys in
        your Spott dashboard.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.