openapi: 3.0.3
info:
  title: Fountain Developer API (Hire API v2)
  description: >-
    The Fountain Developer API lets customers of the Fountain high-volume hiring
    platform programmatically manage their hiring data - applicants, openings
    (funnels), positions, stages, labels, secure documents, interview scheduling
    slots, webhooks, and post-hire workers. All requests are authenticated with
    an API token passed in the X-ACCESS-TOKEN request header.
  termsOfService: https://www.fountain.com/legal/terms-of-use
  contact:
    name: Fountain Support
    email: support@fountain.com
    url: https://developer.fountain.com/reference
  version: '2.0'
servers:
  - url: https://api.fountain.com/v2
    description: Fountain Hire API v2
security:
  - AccessToken: []
tags:
  - name: Applicants
    description: Manage applicants moving through hiring funnels.
  - name: Openings
    description: Manage openings (funnels) - the hiring workflows.
  - name: Positions
    description: Manage the job positions applicants are hired into.
  - name: Stages
    description: Retrieve stages and their available scheduling slots.
  - name: Scheduling
    description: Manage interview / calendar slots and bookings.
  - name: Labels
    description: Assign and manage labels on applicants and stages.
  - name: Documents
    description: Manage secure applicant documents.
  - name: Webhooks
    description: Manage webhook settings for hiring event notifications.
  - name: Workers
    description: Manage post-hire workers.
paths:
  /applicants:
    get:
      operationId: listApplicants
      tags:
        - Applicants
      summary: List all applicants
      description: Returns a paginated list of applicants, filterable by funnel, stage, labels, and timestamps.
      parameters:
        - name: funnel_id
          in: query
          description: Filter by opening (funnel) ID.
          schema:
            type: string
        - name: stage_id
          in: query
          description: Filter by stage ID.
          schema:
            type: string
        - name: stage
          in: query
          description: Filter by stage type.
          schema:
            type: string
            enum: [hired, rejected, archived, background_check, interview, signature]
        - name: labels
          in: query
          description: Comma-separated, URL-encoded list of label titles.
          schema:
            type: string
        - name: cursor
          in: query
          description: Cursor for cursor-based pagination.
          schema:
            type: string
        - name: page
          in: query
          description: Page number for offset pagination.
          schema:
            type: integer
        - name: per_page
          in: query
          description: Number of results per page.
          schema:
            type: integer
      responses:
        '200':
          description: A list of applicants.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicantList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createApplicant
      tags:
        - Applicants
      summary: Create an applicant
      description: Creates a new applicant in a specified funnel.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicantCreate'
      responses:
        '201':
          description: The created applicant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Applicant'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /applicants/{id}:
    parameters:
      - $ref: '#/components/parameters/ApplicantId'
    get:
      operationId: getApplicant
      tags:
        - Applicants
      summary: Get applicant info
      responses:
        '200':
          description: The applicant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Applicant'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: updateApplicant
      tags:
        - Applicants
      summary: Update applicant info
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicantUpdate'
      responses:
        '200':
          description: The updated applicant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Applicant'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteApplicant
      tags:
        - Applicants
      summary: Delete an applicant
      responses:
        '204':
          description: Applicant deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /applicants/{id}/advance:
    parameters:
      - $ref: '#/components/parameters/ApplicantId'
    put:
      operationId: advanceApplicant
      tags:
        - Applicants
      summary: Advance an applicant
      description: Advances an applicant to the next (or specified) stage in the funnel.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                stage_id:
                  type: string
                  description: Target stage to advance the applicant to.
      responses:
        '200':
          description: The advanced applicant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Applicant'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /applicants/advance:
    post:
      operationId: bulkAdvanceApplicants
      tags:
        - Applicants
      summary: Bulk advance multiple applicants
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                applicant_ids:
                  type: array
                  items:
                    type: string
                stage_id:
                  type: string
      responses:
        '200':
          description: Bulk advance accepted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /applicants/{id}/transitions:
    parameters:
      - $ref: '#/components/parameters/ApplicantId'
    get:
      operationId: getApplicantTransitions
      tags:
        - Applicants
      summary: Get transition history
      responses:
        '200':
          description: Applicant transition history.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /applicants/notify:
    post:
      operationId: notifyApplicant
      tags:
        - Applicants
      summary: Notify applicant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                applicant_id:
                  type: string
                message:
                  type: string
      responses:
        '200':
          description: Notification sent.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /applicants/{id}/duplicates:
    parameters:
      - $ref: '#/components/parameters/ApplicantId'
    get:
      operationId: getDuplicateApplicants
      tags:
        - Applicants
      summary: Get duplicate applicants
      responses:
        '200':
          description: List of potential duplicate applicants.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApplicantList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /funnels:
    get:
      operationId: listOpenings
      tags:
        - Openings
      summary: List all openings
      description: Returns all openings (funnels) in the account.
      responses:
        '200':
          description: A list of openings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpeningList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createOpening
      tags:
        - Openings
      summary: Create an opening
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Opening'
      responses:
        '201':
          description: The created opening.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Opening'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /funnels/{id}:
    parameters:
      - $ref: '#/components/parameters/FunnelId'
    get:
      operationId: getOpening
      tags:
        - Openings
      summary: Retrieve opening
      responses:
        '200':
          description: The opening.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Opening'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: updateOpening
      tags:
        - Openings
      summary: Update opening
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Opening'
      responses:
        '200':
          description: The updated opening.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Opening'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteOpening
      tags:
        - Openings
      summary: Delete opening
      responses:
        '204':
          description: Opening deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /funnels/{funnel_id}/stages:
    parameters:
      - name: funnel_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: listOpeningStages
      tags:
        - Openings
      summary: List opening stages
      responses:
        '200':
          description: The stages in the opening.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StageList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /positions:
    get:
      operationId: listPositions
      tags:
        - Positions
      summary: List positions
      responses:
        '200':
          description: A list of positions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PositionList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPosition
      tags:
        - Positions
      summary: Create a position
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Position'
      responses:
        '201':
          description: The created position.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Position'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /positions/{id}:
    parameters:
      - $ref: '#/components/parameters/PositionId'
    get:
      operationId: getPosition
      tags:
        - Positions
      summary: Retrieve position
      responses:
        '200':
          description: The position.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Position'
        '401':
          $ref: '#/components/responses/Unauthorized'
    put:
      operationId: updatePosition
      tags:
        - Positions
      summary: Update position
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Position'
      responses:
        '200':
          description: The updated position.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Position'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deletePosition
      tags:
        - Positions
      summary: Delete position
      responses:
        '204':
          description: Position deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /stages/{id}:
    parameters:
      - $ref: '#/components/parameters/StageId'
    get:
      operationId: getStage
      tags:
        - Stages
      summary: Retrieve stage
      responses:
        '200':
          description: The stage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Stage'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /stages/{id}/available-slots:
    parameters:
      - $ref: '#/components/parameters/StageId'
    get:
      operationId: listStageAvailableSlots
      tags:
        - Stages
      summary: List available slots
      responses:
        '200':
          description: Available scheduling slots for the stage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlotList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /stages/{stage_id}/labels:
    parameters:
      - name: stage_id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: listStageLabels
      tags:
        - Labels
      summary: List all labels in stage
      responses:
        '200':
          description: Labels used in the stage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /applicants/{id}/labels:
    parameters:
      - $ref: '#/components/parameters/ApplicantId'
    get:
      operationId: listApplicantLabels
      tags:
        - Labels
      summary: List labels for applicant
      responses:
        '200':
          description: Labels on the applicant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabelList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /applicants/{id}/labels/{title}:
    parameters:
      - $ref: '#/components/parameters/ApplicantId'
      - name: title
        in: path
        required: true
        description: Label title.
        schema:
          type: string
    put:
      operationId: updateApplicantLabel
      tags:
        - Labels
      summary: Update label for applicant
      description: Assigns or removes a label on an applicant.
      responses:
        '200':
          description: Label updated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /available-slots:
    post:
      operationId: createAvailableSlots
      tags:
        - Scheduling
      summary: Create calendar slots
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Slot'
      responses:
        '201':
          description: The created slot(s).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Slot'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /available-slots/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    patch:
      operationId: updateAvailableSlot
      tags:
        - Scheduling
      summary: Update calendar slot
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Slot'
      responses:
        '200':
          description: The updated slot.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Slot'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteAvailableSlot
      tags:
        - Scheduling
      summary: Delete calendar slot
      responses:
        '204':
          description: Slot deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /available-slots/{id}/confirm:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: bookAvailableSlot
      tags:
        - Scheduling
      summary: Book available slot
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                applicant_id:
                  type: string
      responses:
        '200':
          description: Slot booked.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /booked-slots/{id}/cancel:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: cancelBookedSlot
      tags:
        - Scheduling
      summary: Cancel booked slot
      responses:
        '200':
          description: Booking cancelled.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /applicants/{id}/secure-documents:
    parameters:
      - $ref: '#/components/parameters/ApplicantId'
    get:
      operationId: getApplicantFiles
      tags:
        - Documents
      summary: Get applicant files
      responses:
        '200':
          description: The applicant's secure documents.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /applicants/{id}/secure-documents-upload:
    parameters:
      - $ref: '#/components/parameters/ApplicantId'
    post:
      operationId: uploadApplicantFileToS3
      tags:
        - Documents
      summary: Upload file to S3
      description: Requests a pre-signed URL to upload a secure document directly to S3.
      responses:
        '200':
          description: Upload URL details.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /applicants/{id}/secure-documents-link-upload:
    parameters:
      - $ref: '#/components/parameters/ApplicantId'
    post:
      operationId: linkApplicantS3Files
      tags:
        - Documents
      summary: Link applicant to S3 files
      responses:
        '200':
          description: Files linked to applicant.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /applicants/{id}/secure-documents-approve:
    parameters:
      - $ref: '#/components/parameters/ApplicantId'
    post:
      operationId: approveApplicantDocuments
      tags:
        - Documents
      summary: Approve applicant documents
      responses:
        '200':
          description: Documents approved.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhook-settings:
    get:
      operationId: listWebhookSettings
      tags:
        - Webhooks
      summary: List webhook settings
      responses:
        '200':
          description: A list of webhook settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSettingList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createWebhookSetting
      tags:
        - Webhooks
      summary: Create webhook setting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookSetting'
      responses:
        '201':
          description: The created webhook setting.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSetting'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhook-settings/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getWebhookSetting
      tags:
        - Webhooks
      summary: Retrieve webhook setting
      responses:
        '200':
          description: The webhook setting.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookSetting'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteWebhookSetting
      tags:
        - Webhooks
      summary: Delete webhook setting
      responses:
        '204':
          description: Webhook setting deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /workers:
    get:
      operationId: listWorkers
      tags:
        - Workers
      summary: List workers
      responses:
        '200':
          description: A list of workers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkerList'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /workers/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      operationId: getWorker
      tags:
        - Workers
      summary: Get worker info
      responses:
        '200':
          description: The worker.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Worker'
        '401':
          $ref: '#/components/responses/Unauthorized'
    patch:
      operationId: updateWorker
      tags:
        - Workers
      summary: Update worker
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Worker'
      responses:
        '200':
          description: The updated worker.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Worker'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /workers/{id}/activate:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: activateWorker
      tags:
        - Workers
      summary: Activate worker
      responses:
        '200':
          description: Worker activated.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /workers/{id}/deactivate:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      operationId: deactivateWorker
      tags:
        - Workers
      summary: Deactivate worker
      responses:
        '200':
          description: Worker deactivated.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    AccessToken:
      type: apiKey
      in: header
      name: X-ACCESS-TOKEN
      description: >-
        Your Fountain API token. Request API access by emailing
        support@fountain.com; find your token in your Fountain account settings.
  parameters:
    ApplicantId:
      name: id
      in: path
      required: true
      description: The applicant ID.
      schema:
        type: string
    FunnelId:
      name: id
      in: path
      required: true
      description: The opening (funnel) ID.
      schema:
        type: string
    PositionId:
      name: id
      in: path
      required: true
      description: The position ID.
      schema:
        type: string
    StageId:
      name: id
      in: path
      required: true
      description: The stage ID.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid X-ACCESS-TOKEN.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Applicant:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        phone_number:
          type: string
        funnel_id:
          type: string
        stage_id:
          type: string
        status:
          type: string
        data:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ApplicantCreate:
      type: object
      required:
        - name
        - funnel_id
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        phone_number:
          type: string
        funnel_id:
          type: string
        data:
          type: object
          additionalProperties: true
    ApplicantUpdate:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        phone_number:
          type: string
        data:
          type: object
          additionalProperties: true
    ApplicantList:
      type: object
      properties:
        applicants:
          type: array
          items:
            $ref: '#/components/schemas/Applicant'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Opening:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        position_id:
          type: string
        location_id:
          type: string
        active:
          type: boolean
        created_at:
          type: string
          format: date-time
    OpeningList:
      type: object
      properties:
        funnels:
          type: array
          items:
            $ref: '#/components/schemas/Opening'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Position:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        external_id:
          type: string
    PositionList:
      type: object
      properties:
        positions:
          type: array
          items:
            $ref: '#/components/schemas/Position'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Stage:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        type:
          type: string
        position:
          type: integer
    StageList:
      type: object
      properties:
        stages:
          type: array
          items:
            $ref: '#/components/schemas/Stage'
    Slot:
      type: object
      properties:
        id:
          type: string
        stage_id:
          type: string
        start_time:
          type: string
          format: date-time
        end_time:
          type: string
          format: date-time
        capacity:
          type: integer
        booked_count:
          type: integer
        location:
          type: string
    SlotList:
      type: object
      properties:
        available_slots:
          type: array
          items:
            $ref: '#/components/schemas/Slot'
    Label:
      type: object
      properties:
        title:
          type: string
        color:
          type: string
    LabelList:
      type: object
      properties:
        labels:
          type: array
          items:
            $ref: '#/components/schemas/Label'
    Document:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        status:
          type: string
        url:
          type: string
          format: uri
        created_at:
          type: string
          format: date-time
    DocumentList:
      type: object
      properties:
        secure_documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'
    WebhookSetting:
      type: object
      properties:
        id:
          type: string
        url:
          type: string
          format: uri
        event:
          type: string
        funnel_id:
          type: string
        stage_id:
          type: string
    WebhookSettingList:
      type: object
      properties:
        webhook_settings:
          type: array
          items:
            $ref: '#/components/schemas/WebhookSetting'
    Worker:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string
          format: email
        status:
          type: string
        position_id:
          type: string
        location_id:
          type: string
    WorkerList:
      type: object
      properties:
        workers:
          type: array
          items:
            $ref: '#/components/schemas/Worker'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Pagination:
      type: object
      properties:
        next_cursor:
          type: string
        per_page:
          type: integer
        total:
          type: integer
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string