openapi: 3.0.1
info:
  title: Empowill API - Files
  version: "2.0"
  description: |
    Files module of the Empowill API v2: upload and download of binary content (company and provider logos, user profile pictures, training documents, certifications, medic exams, clearances, interview PDFs, imports and exports).

    **Signed URLs — heavy attachments, resumable downloads.** Send `Accept: application/json` on any file `GET` and the API returns `{"url": "<signed Google Cloud Storage URL>"}` (valid 15 minutes) instead of the bytes: the download then streams straight from GCS, needs no `Authorization` header and supports HTTP `Range` for resumable transfers of very large files. The same header on a file `POST` with a JSON body (`{"contentType": "...", "name": "..."}`) returns a signed `PUT` URL for direct uploads. See the [signed URLs guide](./index.html#files) for examples in Python, TypeScript and Go.

    File endpoints otherwise differ from the rest of the API:
    - **Uploads** use `multipart/form-data` with the binary content in a `file` form field, not a JSON body.
    - **Downloads** return the raw binary content (`image/*`, `application/pdf`, `text/csv`...), often with a `Content-Disposition` header; they are not JSON envelopes.
    - Some resources are versioned through an optional `generation` query parameter.
    - Authentication and headers are the same as the rest of the API (OAuth2 Bearer token, `Company-Id`).

    Shared concepts (authentication, required headers, time handling, errors, list requests) are described on the documentation portal home page.
  contact:
    name: Toussaint Boos
    email: toussaint.b@empowill.com
    url: https://calendar.app.google/ywCE5askKfof2mxD8
servers:
  - url: https://demo.api.empowill.com
tags:
  - name: BlobService
paths:
  /v2/files/company/{companyId}/logo:
    post:
      summary: Create/Update a new company logo.
      description: |
        The API will check within the payload the type of file passed.

        The file size cannot be superior to 20Mib and be either an `image/jpeg` or `image/png` MIME type.

        Small note about the `empowill` company ID, you cannot upload a file for this specific company, the API won't return an error, but the image won't be uploaded.
      operationId: BlobService_Create
      parameters:
        - in: path
          name: companyId
          schema:
            type: string
          required: true
      responses:
        "200":
          description: A successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/httpError"
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/v2CreateCompanyLogo"
        required: true
      tags:
        - BlobService
      security:
        - OAuth2: []
    get:
      summary: Get company logo content.
      description: |
        Get the company's logo content.
      operationId: BlobService_Get
      parameters:
        - in: path
          name: companyId
          schema:
            type: string
          required: true
        - in: query
          name: generation
          description: generation parameter describes the version of the file.
          schema:
            type: string
      responses:
        "200":
          description: A successful response.
        default:
          description: An unexpected error response.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/httpError"
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/v2CreateCompanyLogo"
        required: true
      tags:
        - BlobService
      security:
        - OAuth2: []
  /v2/files/company/{companyId}/campaign/{campaignId}/interview/{interviewId}/pdf:
    get:
      summary: Get an interview PDF result.
      operationId: BlobService_Get8Interview_PDF
      parameters:
        - in: path
          name: companyId
          schema:
            type: string
          required: true
        - in: path
          name: campaignId
          schema:
            type: string
          required: true
        - in: path
          name: interviewId
          schema:
            type: string
          required: true
        - in: query
          name: generation
          description: generation parameter describes the version of the file.
          schema:
            type: string
      responses:
        "200":
          description: A successful response.
          content:
            application/pdf:
              schema:
                type: string
                format: binary
    post:
      summary: Add PDF for a given interview
      parameters:
        - name: companyId
          in: path
          required: true
          description: ID of the company
          schema:
            type: string
        - name: campaignId
          in: path
          required: true
          description: ID of the campaign
          schema:
            type: string
        - name: interviewId
          in: path
          required: true
          description: ID of the campaign
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: Interview PDF successfully uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: "The endpoint from which to GET the uploaded PDF"
                    example: "https://domain.com/company/123/campaign/123/interview/123/pdf"
        "400":
          description: Bad Request
        "403":
          description: Forbidden
        "500":
          description: Internal Server Error
  /v2/files/company/{companyId}/users/{userId}/notes_categories/{categoryId}/notes/{noteId}/:
    post:
      summary: Add file to a note
      operationId: addFileToNote
      tags:
        - Note Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: categoryId
          in: path
          required: true
          schema:
            type: string
        - name: noteId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: File successfully uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: "The endpoint from which to GET the uploaded file"
                    example: "https://domain.com/company/123/users/456/notes_categories/789/notes/234/filename.pdf"
        "400":
          description: Bad Request
        "403":
          description: Forbidden
        "500":
          description: Internal Server Error
    get:
      summary: Get list of files metadata of a note
      operationId: getNoteFilesMetadata
      tags:
        - Note Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: categoryId
          in: path
          required: true
          schema:
            type: string
        - name: noteId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: List of files metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  file_attributes:
                    type: array
                    items:
                      $ref: "#/components/schemas/FileAttribute"
        "500":
          description: Internal Server Error
  /v2/files/company/{companyId}/users/{userId}/notes_categories/{categoryId}/notes/{noteId}/{fileName}:
    delete:
      summary: Delete a file from a note
      operationId: deleteFileFromNote
      tags:
        - Note Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: categoryId
          in: path
          required: true
          schema:
            type: string
        - name: noteId
          in: path
          required: true
          schema:
            type: string
        - name: fileName
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: File successfully deleted
        "500":
          description: Internal Server Error
    get:
      summary: Get file content
      operationId: getNoteFileContent
      tags:
        - Note Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: categoryId
          in: path
          required: true
          schema:
            type: string
        - name: noteId
          in: path
          required: true
          schema:
            type: string
        - name: fileName
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "500":
          description: Internal Server Error
  /v2/files/company/{companyId}/news/{newsId}/cover:
    post:
      summary: Upload cover image for a news item
      operationId: uploadNewsCover
      tags:
        - News Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: newsId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
                  description: image/jpeg or image/png
      responses:
        "200":
          description: Cover image successfully uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
        "500":
          description: Internal Server Error
    get:
      summary: Get news cover image
      operationId: getNewsCover
      tags:
        - News Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: newsId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Cover image content
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
        "500":
          description: Internal Server Error
    delete:
      summary: Delete news cover image
      operationId: deleteNewsCover
      tags:
        - News Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: newsId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Cover image successfully deleted
        "500":
          description: Internal Server Error
  /v2/files/company/{companyId}/news/{newsId}/attachment:
    post:
      summary: Add file to a news item
      operationId: addFileToNews
      tags:
        - News Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: newsId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: File successfully uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
        "500":
          description: Internal Server Error
    get:
      summary: Get list of files metadata of a news item
      operationId: getNewsFilesMetadata
      tags:
        - News Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: newsId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: List of files metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  file_attributes:
                    type: array
                    items:
                      $ref: "#/components/schemas/FileAttribute"
        "500":
          description: Internal Server Error
  /v2/files/company/{companyId}/news/{newsId}/attachment/{fileName}:
    delete:
      summary: Delete a file from a news item
      operationId: deleteFileFromNews
      tags:
        - News Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: newsId
          in: path
          required: true
          schema:
            type: string
        - name: fileName
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: File successfully deleted
        "500":
          description: Internal Server Error
    get:
      summary: Get file content
      operationId: getNewsFileContent
      tags:
        - News Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: newsId
          in: path
          required: true
          schema:
            type: string
        - name: fileName
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "500":
          description: Internal Server Error
  /v2/files/company/{companyId}/users/{userId}/achieved-medic-exams/{achievedMedicExamId}:
    post:
      summary: Add file to an achieved medic exam
      operationId: addFileToAchievedMedicExam
      tags:
        - Achieved Medic Exam Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: achievedMedicExamId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: File successfully uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: "The endpoint from which to GET the uploaded file"
                    example: "https://domain.com/company/123/users/456/achieved-medic-exams/789/filename.pdf"
        "400":
          description: Bad Request
        "403":
          description: Forbidden
        "500":
          description: Internal Server Error
    get:
      summary: Get list of files metadata of an achieved medic exam
      operationId: getAchievedMedicExamFilesMetadata
      tags:
        - Achieved Medic Exam Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: achievedMedicExamId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: List of files metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  file_attributes:
                    type: array
                    items:
                      $ref: "#/components/schemas/FileAttribute"
        "500":
          description: Internal Server Error
  /v2/files/company/{companyId}/users/{userId}/achieved-medic-exams/{achievedMedicExamId}/{fileName}:
    delete:
      summary: Delete a file from an achieved medic exam
      operationId: deleteFileFromAchievedMedicExam
      tags:
        - Achieved Medic Exam Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: achievedMedicExamId
          in: path
          required: true
          schema:
            type: string
        - name: fileName
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: File successfully deleted
        "500":
          description: Internal Server Error
    get:
      summary: Get file content
      operationId: getAchievedMedicExamFileContent
      tags:
        - Achieved Medic Exam Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: achievedMedicExamId
          in: path
          required: true
          schema:
            type: string
        - name: fileName
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "500":
          description: Internal Server Error
  /v2/files/company/{companyId}/training/{trainingId}:
    post:
      summary: Add file to a training
      operationId: addFileToTraining
      tags:
        - Training Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: trainingId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: File successfully uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: "The endpoint from which to GET the uploaded file"
                    example: "https://domain.com/company/123/training/456/filename.pdf"
        "400":
          description: Bad Request
        "403":
          description: Forbidden
        "500":
          description: Internal Server Error
    get:
      summary: Get list of files metadata of a training
      operationId: getTrainingFilesMetadata
      tags:
        - Training Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: trainingId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: List of files metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  file_attributes:
                    type: array
                    items:
                      $ref: "#/components/schemas/FileAttribute"
        "500":
          description: Internal Server Error
  /v2/files/company/{companyId}/training/{trainingId}/{fileName}:
    delete:
      summary: Delete a file from a training
      operationId: deleteFileFromTraining
      tags:
        - Training Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: trainingId
          in: path
          required: true
          schema:
            type: string
        - name: fileName
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: File successfully deleted
        "500":
          description: Internal Server Error
    get:
      summary: Get file content
      operationId: getTrainingFileContent
      tags:
        - Training Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: trainingId
          in: path
          required: true
          schema:
            type: string
        - name: fileName
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "500":
          description: Internal Server Error
  /v2/files/company/{companyId}/users/{userId}/achieved-certifications/{achievedCertificationId}:
    post:
      summary: Add file to an achieved certification
      operationId: addFileToAchievedCertification
      tags:
        - Achieved Certification Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: achievedCertificationId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: File successfully uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: "The endpoint from which to GET the uploaded file"
                    example: "https://domain.com/company/123/users/456/notes_categories/789/notes/234/filename.pdf"
        "400":
          description: Bad Request
        "403":
          description: Forbidden
        "500":
          description: Internal Server Error
    get:
      summary: Get list of files metadata of an achieved certification
      operationId: getAchievedCertificationFilesMetadata
      tags:
        - Achieved Certification Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: achievedCertificationId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: List of files metadata
          content:
            application/json:
              schema:
                type: object
                properties:
                  file_attributes:
                    type: array
                    items:
                      $ref: "#/components/schemas/FileAttribute"
        "500":
          description: Internal Server Error
  /v2/files/company/{companyId}/users/{userId}/achieved-certifications/{achievedCertificationId}/{fileName}:
    delete:
      summary: Delete a file from an achieved certification
      operationId: deleteFileFromAchievedCertification
      tags:
        - Achieved Certification Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: achievedCertificationId
          in: path
          required: true
          schema:
            type: string
        - name: fileName
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: File successfully deleted
        "500":
          description: Internal Server Error
    get:
      summary: Get file content
      operationId: getAchievedCertificationFileContent
      tags:
        - Achieved Certification Attachments
      parameters:
        - name: companyId
          in: path
          required: true
          schema:
            type: string
        - name: userId
          in: path
          required: true
          schema:
            type: string
        - name: achievedCertificationId
          in: path
          required: true
          schema:
            type: string
        - name: fileName
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: File content
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "500":
          description: Internal Server Error
  /v2/files/users/{userId}/logo:
    post:
      summary: Add logo to an account
      parameters:
        - name: userId
          in: path
          required: true
          description: ID of the user
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: Logo successfully uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: "The endpoint from which to GET the uploaded logo"
                    example: "https://domain.com/users/123/logo"
        "400":
          description: Bad Request
        "403":
          description: Forbidden
        "500":
          description: Internal Server Error
    delete:
      summary: Delete a logo from an account
      parameters:
        - name: userId
          in: path
          required: true
          description: ID of the user
          schema:
            type: string
      responses:
        "200":
          description: Logo deleted successfully
        "403":
          description: Forbidden
        "500":
          description: Internal Server Error
    get:
      summary: Get logo content
      parameters:
        - name: userId
          in: path
          required: true
          description: ID of the user
          schema:
            type: string
      responses:
        "200":
          description: Logo content retrieved successfully
          content:
            image/*:
              schema:
                type: string
                format: binary
        "404":
          description: Logo not found
        "500":
          description: Internal Server Error
  /v2/files/company/{companyId}/training-provider/{trainingProviderId}/logo:
    post:
      summary: Add logo to a training provider
      parameters:
        - name: companyId
          in: path
          required: true
          description: ID of the company
          schema:
            type: string
        - name: trainingProviderId
          in: path
          required: true
          description: ID of the training provider
          schema:
            type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: Logo successfully uploaded
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    description: "The endpoint from which to GET the uploaded logo"
                    example: "https://domain.com/company/123/training-provider/456/logo"
        "400":
          description: Bad Request
        "403":
          description: Forbidden
        "500":
          description: Internal Server Error
    delete:
      summary: Delete a logo from a training provider
      parameters:
        - name: companyId
          in: path
          required: true
          description: ID of the company
          schema:
            type: string
        - name: trainingProviderId
          in: path
          required: true
          description: ID of the training provider
          schema:
            type: string
      responses:
        "200":
          description: Logo deleted successfully
        "403":
          description: Forbidden
        "500":
          description: Internal Server Error
    get:
      summary: Get logo content
      parameters:
        - name: companyId
          in: path
          required: true
          description: ID of the company
          schema:
            type: string
        - name: trainingProviderId
          in: path
          required: true
          description: ID of the training provider
          schema:
            type: string
      responses:
        "200":
          description: Logo content retrieved successfully
          content:
            image/*:
              schema:
                type: string
                format: binary
        "404":
          description: Logo not found
        "500":
          description: Internal Server Error
  /v2/files/imports/template:
    get:
      summary: Get a templated csv for the requested importType.
      operationId: BlobService_GetImportType
      parameters:
        - in: query
          name: type
          schema:
            $ref: "#/components/schemas/v2ImportType"
          required: true
      responses:
        "200":
          description: A successful response.
          content:
            text/csv:
              schema:
                type: string
                format: binary
  /v2/files/company/{companyId}/clearances/{clearanceId}:
    post:
      summary: Post a clearance's PDF
      parameters:
        - in: path
          name: companyId
          schema:
            type: string
          required: true
        - in: path
          name: clearanceId
          schema:
            type: string
          required: true
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        "200":
          description: Clearance PDF successfully uploaded
        "403":
          description: Forbidden
        "500":
          description: Internal Server Error
    get:
      summary: Get a clearance's PDF
      parameters:
        - in: path
          name: companyId
          schema:
            type: string
          required: true
        - in: path
          name: clearanceId
          schema:
            type: string
          required: true
      responses:
        "200":
          description: Clearance PDF successfully downloaded
          content:
            application/pdf:
              schema:
                type: string
                format: binary
        "403":
          description: Forbidden
        "500":
          description: Internal Server Error

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: >-
        This method is only available for v2

        open id standard access token

        Api host is compliant with 0auth2 standard / open id standards

        Automatic configuration is supported: https://demo.api.empowill.com/.well-known/openid-configuration

        You can access one or several customers tenants depending on your given accesses

        Prefix with "Bearer " in authorization headers
      flows:
        clientCredentials:
          tokenUrl: /oauth2/token
          scopes:
            offline: allow refresh token generation
            openid: access token hint and additional openid standard capacities
  schemas:
    v2CreateCompanyLogo:
      type: object
      properties:
        file:
          type: string
          format: binary
    httpError:
      type: object
      properties:
        message:
          type: string
        status:
          type: integer
    FileAttribute:
      type: object
      properties:
        Name:
          type: string
        URL:
          type: string
        Encoding:
          type: string
