openapi: 3.0.0
info:
  title: CSV
  description: This is the documentation for the Quick Enrollment CSV API in ID360.
  version: 1.1.1
servers:
  - url: 'https://id360.manageengine.com/api/v1'
    description: 'API Endpoint'
tags:
  - name: qe-csv
    description: Quick Enrollment CSV APIs
paths:
  /protection/quick-enrollment/upload-csv:
    post:
      tags:
        - qe-csv
      summary: Upload Quick Enrollment CSV
      description: >
        The Upload CSV API can be used to upload a CSV file for quick enrollment.
        <br>
        Note: This API will return job resource
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/csvFileUpload'
      responses:
        '202':
          description: 'Accepted'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/csvFileUpload'
                  links:
                    $ref: '#/components/schemas/links'
        '400':
          description: 'Bad Request'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/csvUploadNestedError'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.quick_enrollment.ALL
            - id360.quick_enrollment.WRITE
            - id360.quick_enrollment.CREATE
  /protection/quick-enrollment/upload-smartcards:
    post:
      tags:
        - quick-enrollment
      summary: Upload Quick Enrollment CSV for Smart cards
      description: >
        The Upload CSV for Smart cards API can be used to upload a CSV file for quick enrollment of smart cards.
        <br>
        Note: This API will return job resource
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/uploadSmartcards'
      responses:
        '202':
          description: 'Accepted'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/uploadSmartcards'
                  links:
                    $ref: '#/components/schemas/links'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.quick_enrollment.ALL
            - id360.quick_enrollment.WRITE
            - id360.quick_enrollment.CREATE
  /protection/quick-enrollment/sample-csv:
    get:
      tags:
        - quick-enrollment
      summary: Download Sample CSV for Quick Enrollment
      description: 'The Download Sample CSV API can be used to download a sample CSV file for quick enrollment.'
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
        - $ref: '#/components/parameters/factorConfigs'
      responses:
        '200':
          description: 'OK'
          content:
            application/csv:
              schema:
                type: string
                format: binary
                description: 'The sample CSV file for quick enrollment.'
                example: 'sample_quick_enrollment.csv'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.quick_enrollment.ALL
            - id360.quick_enrollment.READ
components:
  parameters:
    authorization:
      name: Authorization
      in: header
      schema:
        type: string
      description: 'Authorization OAuth token for the API'
      required: true
      example: 'Zoho-oauthtoken 1000.41d**************125f'
    acceptHeader:
      name: Accept
      in: header
      schema:
        type: string
      description: 'Accept header for the API'
      required: false
      example: 'application/json'
    factorConfigs:
      name: factor_configs
      in: query
      required: false
      description: The comma-separated list of factor configuration ids to be included in the sample CSV download.
      example: '2000000293042,2000000293043'
      schema:
        type: string
  schemas:
    csvFileUpload:
      allOf:
        - type: object
          properties:
            file:
              type: string
              format: binary
              description: 'CSV file to be uploaded for quick enrollment'
              example: 'quick_enrollment.csv'
              writeOnly: true
            factor_configs:
              type: array
              description: List of factor configuration IDs to be used for quick enrollment.
              items:
                type: integer
                example: 2000000283042
              example:
                - 2000000283042
                - 2000000283043
                - 2000000283044
              writeOnly: true
            file_encoding:
              type: string
              description: Encoding of the CSV file.
              enum:
                - Big5
                - EUC-JP
                - EUC-KR
                - GB2312
                - ISO-2022-JP
                - ISO-8859-1
                - KOI8-R
                - Shift_JIS
                - US-ASCII
                - UTF-8
                - WINDOWS-1251
                - X-WINDOWS-ISO2022JP
              example: UTF-8
              writeOnly: true
            overwrite_enrollment_data:
              type: boolean
              description: Indicates whether to overwrite existing enrollment data for the users in the CSV file.
              example: true
              writeOnly: true
        - $ref: '#/components/schemas/acceptJobResponse'
        - type: object
          properties:
            message:
              type: string
              description: Message providing additional information about the CSV file upload status.
              example: Enrollment Process is initiated, check jobs for current status
              readOnly: true

    uploadSmartcards:
      allOf:
        - type: object
          properties:
            file:
              type: string
              format: binary
              description: ZIP file containing smartcard data for quick enrollment.
              example: 'smartcards.zip'
              writeOnly: true
            factor_configs:
              type: array
              description: List of factor configuration IDs to be used for quick enrollment.
              items:
                type: integer
                example: 2000000283042
              example:
                - 2000000283042
                - 2000000283043
                - 2000000283044
              writeOnly: true
            certificate_filename_pattern:
              type: string
              description: Pattern for the certificate filenames in the ZIP file.
              enum:
                - Primary Email
                - Employee ID
                - Mobile Number
              example: Primary Email
              writeOnly: true
            overwrite_enrollment_data:
              type: boolean
              description: Indicates whether to overwrite existing enrollment data for the users in the ZIP file.
              example: true
              writeOnly: true
        - $ref: '#/components/schemas/acceptJobResponse'
        - type: object
          properties:
            message:
              type: string
              description: Message providing additional information about the smartcard upload status.
              example: Enrollment Process is initiated, check jobs for current status
              readOnly: true

    acceptJobResponse:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the job.
          example: '2000000293042'
          readOnly: true
        status:
          type: string
          description: Status of the CSV file upload.
          enum:
            - 'QUEUED'
            - 'RUNNING'
            - 'WARNING'
            - 'COMPLETED'
            - 'ERROR'
          example: RUNNING
          readOnly: true
        message:
          type: string
          description: Message providing additional information about the accept response.
          example: Process is initiated, check jobs for current status.
          readOnly: true

    links:
      type: object
      readOnly: true
      properties:
        status:
          type: object
          properties:
            href:
              type: string
              example: /jobs/2000000293042
              description: URL to get the status of the job

    csvUploadNestedError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '00000114'
              description: 'Error code indicating the type of error.'
            title:
              type: string
              example: 'CSV_UPLOAD_FAILED'
              description: 'Title of the error.'
            detail:
              type: string
              description: 'Detailed message about the error.'
              example: "Selected CSV file's header is not consistent with this import option."
            causes:
              type: array
              items:
                type: object
                properties:
                  title:
                    type: string
                    example: 'DUPLICATE_COLUMNS'
                    description: 'Specific error title for the cause.'
                  detail:
                    type: string
                    example: 'Your file contains duplicate column names. Ensure all column headers are unique.'
                    description: 'Detailed message about the cause of the error.'

    unauthorized:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '00000101'
            title:
              type: string
              example: 'Unauthorized'
            detail:
              type: string
              example: 'The OAuth token is invalid.'
    serverError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '00000000'
            title:
              type: string
              example: 'Internal Server Error'
            detail:
              type: string
              example: 'An unexpected internal error has occurred on the server. Please try again later.'
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      x-authorization-example: 'Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f'
      flows:
        authorizationCode:
          authorizationUrl: 'https://accounts.zoho.com/oauth/v2/auth'
          tokenUrl: 'https://accounts.zoho.com/oauth/v2/token'
          scopes:
            id360.quick_enrollment.READ: 'Get quick enrollment details'
            id360.quick_enrollment.WRITE: 'Create/Update/Delete quick enrollment'
            id360.quick_enrollment.DELETE: 'Delete quick enrollment'
            id360.quick_enrollment.CREATE: 'Create quick enrollment'
            id360.quick_enrollment.UPDATE: 'Update quick enrollment'