DataExtraction.yaml

openapi: 3.0.1
info:

  title: Data Extraction APIssssss
  description: The DataExtraction API data from CXone for external
    reporting purposes.  For example, you can extract QM Workflow data. You must generatesds
    a key in order to use this API.
  contact:
    email: R&DApiTeam@niceincontact.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: V13
servers:
- url: https://na1.nice-incontact.com/data-extraction/V1
  description: Production Oregon Environment (uses live data)
  variables: {}
- url: https://au1.nice-incontact.com/data-extraction/V1
  description: Production Australia Environment (uses live data)
  variables: {}
- url: https://eu1.niceincontact.com/data-extraction/V1
  description: Production Frankfurt Environment (uses live data)
  variables: {}
- url: https://na1.staging.nice-incontact.com/data-extraction/V1
  description: Staging Environment
  variables: {}
- url: https://na1.test.nice-incontact.com/data-extraction/V1
  description: Test Environment
  variables: {}
- url: https://nvir.test.niceincontact.com/data-extraction/V1
  description: North Virginia Test Environment
  variables: {}
- url: https://na1.dev.nice-incontact.com/data-extraction/V1
  description: Dev Environment
  variables: {}
- url: https://virtserver.swaggerhub.com/nice-api/data-extraction/V1
  description: SwaggerHub API Auto Mocking for data extraction
  variables: {}
tags:
- name: Extracting Data
- name: Internal Data Extraction APIs
- name: UNPUBLISHED
paths:
  /jobs:
    get:
      tags:
      - Extracting Data
      summary: Gets status for all jobs.
      description: View a list of all job statuses per tenant. Possible statuses are
        Running, Succeeded, Failed, Cancelled, and Expired.
      operationId: getAllJobs
      responses:
        200:
          description: Success. Retrieved status for all jobs.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jobsResponse'
        401:
          description: Unauthorized. Invalid credentials.
        403:
          description: Forbidden. User does not have permission to view job status.
        500:
          description: Internal Server Error
      security:
      - bearerAuth: []
      x-cxone-audience: company-internal
      x-cxone-api-key: 1168ae16-a6bb-4bf9-893e-3b07347a5ea3
    post:
      tags:
      - Extracting Data
      summary: Prepares requested data for extraction.
      description: After a request to extract data is made, the data is gathered and
        prepared for extraction. The data is available in S3 as a csv file for 24
        hours. When done, a job ID is returned.
      operationId: extractData
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/exportRequest'
        required: true
      responses:
        202:
          description: Success. Successfully exported asynchronous job.
          content:
            text/plain:
              schema:
                type: string
        400:
          description: Invalid request. Incorrect date filters, etc.
        401:
          description: Unauthorized. Invalid credentials.
        403:
          description: Forbidden. User does not have permission to view job status.
        404:
          description: Not Found. Missing entity or invalid version.
        500:
          description: Internal Server Error
      security:
      - bearerAuth: []
      x-cxone-audience: company-internal
      x-cxone-api-key: a52e0eb1-5cfb-4da6-9b49-ba3f36b91735
  
  /jobs/{jobId}:
    get:
      tags:
      - Extracting Data
      summary: Gets a specific job status.
      description: View the status for a specific job per its job Id. If a job was
        successful, a url to access the extracted data is returned and is accessible
        for 30 seconds (not including the time it takes to download the file). If
        the job failed, an error message is returned. The link  can be used to access
        the extracted data. Possible job statuses are Running, Succeeded, Failed,
        Expired, and Cancelled.
      operationId: getJobStatus
      parameters:
      - name: jobId
        in: path
        description: Unique identifier for the request that was made to extract customer
          data.
        required: true
        schema:
          type: string
      responses:
        200:
          description: Success. Retrieved job status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/jobResponse'
        401:
          description: Unauthorized. Invalid credentials.
        403:
          description: Forbidden. User does not have permission to view job status.
        404:
          description: Not found. Job not found.
        500:
          description: Internal Server Error
      security:
      - bearerAuth: []
      x-cxone-audience: company-internal
      x-cxone-api-key: 6cd12056-d74b-4f0a-8d0e-7039e65c5551
  /jobs/sync:
    post:
      tags:
      - Extracting Data
      summary: Prepares requested data for extraction.
      description: After a request to extract data is made, the data is gathered and
        prepared for extraction. A url to access the extracted data is returned and
        is accessible for 30 seconds (not including the time it takes to download
        the file).
      operationId: extractDataSync
      deprecated: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/exportRequest'
        required: true
      responses:
        200:
          description: Success. Successfully exported synchronous request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/exportResponse'
        400:
          description: Invalid request. Incorrect date filters, etc.
        401:
          description: Unauthorized. Invalid credentials.
        403:
          description: Forbidden. User does not have permission to view job status.
        404:
          description: Not Found. Missing entity or invalid version.
        500:
          description: Internal Server Error
      security:
      - bearerAuth: []
      x-cxone-audience: external-public
      x-cxone-api-key: d853057d-2c94-4cdd-b80e-73c7d029fb81
  /entities/{entityName}:
    get:
      tags:
      - Internal Data Extraction APIs
      summary: Gets an entity according to the version.
      description: Gets an entity according to the version.
      operationId: getEntity
      parameters:
      - name: entityName
        in: path
        description: Name of the entity you are getting.
        required: true
        schema:
          type: string
      - name: entityVersion
        in: query
        description: Entity version you are getting.
        schema:
          type: string
      responses:
        200:
          description: Success. Retrieved the entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/entityResponse'
        400:
          description: Invalid request. Missing entity or version.
        401:
          description: Unauthorized. Invalid credentials.
        403:
          description: Forbidden. User does not have permission to view job status.
        404:
          description: Not found. Entity or version does not exist.
        500:
          description: Internal Server Error
      security:
      - bearerAuth: []
      x-cxone-audience: company-internal
      x-cxone-api-key: 4d4bc2bb-2527-41bb-8d95-2bbb857321e0
    delete:
      tags:
      - Internal Data Extraction APIs
      summary: Deletes a specific version of an entity.
      description: Deletes a specific version of an entity.
      operationId: deleteEntity
      parameters:
      - name: entityName
        in: path
        description: Name of the entity you are deleting.
        required: true
        schema:
          type: string
      - name: entityVersion
        in: query
        description: Entity version you are deleting.
        schema:
          type: string
      responses:
        201:
          description: Success. Deletes and entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/entityResponse'
        400:
          description: Invalid request. Missing entity or version.
        401:
          description: Unauthorized. Invalid credentials.
        403:
          description: Forbidden. User does not have permission to view job status.
        404:
          description: Not found. Version does not exist.
        500:
          description: Internal Server Error
      security:
      - bearerAuth: []
      x-cxone-audience: company-internal
      x-cxone-api-key: e4a3be9b-2f10-4318-8e94-60d5509f2e34
    patch:
      tags:
      - Internal Data Extraction APIs
      summary: Updates an existing entity based on a specific version.
      description: Updates an existing entity based on a specific version. Not all
        fields are mandatory. Returns a new entity.
      operationId: updateEntity
      parameters:
      - name: entityName
        in: path
        description: Name of the entity you are updating.
        required: true
        schema:
          type: string
      - name: entityVersion
        in: query
        description: Entity version you are updating.
        schema:
          type: string
      requestBody:
        description: Updates an entity.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/updateEntityRequest'
        required: true
      responses:
        201:
          description: Success. Updates an entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/entityPackResponse'
        400:
          description: Invalid request. Invalid entity fields or invalid entity.
        401:
          description: Unauthorized. Invalid credentials.
        403:
          description: Forbidden. User does not have permission to modify entities.
        404:
          description: Not found. Entity or version does not exist.
        500:
          description: Internal Server Error
      security:
      - bearerAuth: []
      x-cxone-audience: company-internal
      x-cxone-api-key: 26316cdf-6e59-4f21-a7c5-ce9a0849e862
  /entities:
    post:
      tags:
      - Internal Data Extraction APIs
      summary: Adds a new entity.
      description: Adds a new entity.
      operationId: saveEntity
      requestBody:
        description: Adds an entity request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/addEntityRequest'
        required: true
      responses:
        201:
          description: Success. Created a new entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/entityInfoResponse'
        400:
          description: Invalid request. Missing entity, invalid version, incorrect
            date filters, etc.)
        401:
          description: Unauthorized. Invalid credentials.
        403:
          description: Forbidden. User does not have permission to modify entities.
        500:
          description: Internal Server Error
      security:
      - bearerAuth: []
      x-cxone-audience: company-internal
      x-cxone-api-key: 928963d4-e65f-47b9-9829-42e837bcb4eb
  /entities/description/{entityName}:
    get:
      tags:
      - Internal Data Extraction APIs
      summary: Gets an entity description according to the version.
      description: Gets an entity description according to the version.
      operationId: getEntityDescription
      parameters:
      - name: entityName
        in: path
        description: Name of the entity you are getting.
        required: true
        schema:
          type: string
      - name: entityVersion
        in: query
        description: Entity version you are getting.
        schema:
          type: string
      responses:
        200:
          description: Success. Retrieved the entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/entityResponse'
        400:
          description: Invalid request. Missing entity or version.
        401:
          description: Unauthorized. Invalid credentials.
        403:
          description: Forbidden. User does not have permission to view job status.
        404:
          description: Not found. Entity or version does not exist.
        500:
          description: Internal Server Error
      security:
      - bearerAuth: []
      x-cxone-audience: company-internal
      x-cxone-api-key: 4d4bc2bb-2527-41bb-8d95-2bbb857321e0
  /entities/if-not-exists/{validateEntityVersion}:
    post:
      tags:
      - Internal Data Extraction APIs
      summary: Adds a new entity.
      description: Adds a new entity.
      operationId: saveEntityIfNotExists
      parameters:
      - name: validateEntityVersion
        in: path
        description: Name of the entity you are getting.
        required: true
        schema:
          type: string
      requestBody:
        description: Adds an entity request.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/addEntityRequest'
        required: true
      responses:
        201:
          description: Success. Created a new entity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/entityInfoResponse'
        400:
          description: Invalid request. Missing entity, invalid version, incorrect
            date filters, etc.)
        401:
          description: Unauthorized. Invalid credentials.
        403:
          description: Forbidden. User does not have permission to modify entities.
        500:
          description: Internal Server Error
      security:
      - bearerAuth: []
      x-cxone-audience: company-internal
      x-cxone-api-key: 4f48ae75-a75b-438f-b3b2-6ff5754d0316
components:
  schemas:
    exportRequest:
      type: object
      properties:
        entityName:
          type: string
          description: Name of entity to extract.
          example: qm-workflows
        version:
          type: string
          description: Version of entity to extract.
          example: "3"
        startDate:
          type: string
          description: Date from which to start extracting data. For example, extract
            data starting from May 22, 2019.
          format: date
        endDate:
          type: string
          description: Date from which to stop extracting data. For example, extract
            data until May 29, 2019.
          format: date
      description: Parameters that need to be provided in order to extract data.
    exportResponse:
      type: object
      properties:
        url:
          type: string
          description: A pre-signed URL when a job for extracting data is successful.
          example: https://s3.example.amazonaws.com/results-bucket/data-extraction/{details}
      description: Successful response includes a pre-signed URL for result
    jobState:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the job.
          format: uuid
        status:
          type: string
          description: The status of the job.
          enum:
          - RUNNING
          - SUCCEEDED
          - FAILED
          - CANCELLED
          - EXPIRED
      description: Status and ID of the job.
    jobsResponse:
      type: object
      properties:
        jobs:
          type: array
          description: List of statuses for all jobs.
          items:
            $ref: '#/components/schemas/jobState'
      description: Displays statuses for all jobs.
    jobResponse:
      type: object
      properties:
        jobStatus:
          $ref: '#/components/schemas/jobStatus'
      description: Displays the job status.
    jobResult:
      type: object
      properties:
        url:
          type: string
          description: A url to access the extracted data is returned when a job for
            extracting data is successful.
          example: https://s3.example.amazonaws.com/results-bucket/data-extraction/{details}
        errorMessage:
          type: string
          description: Error message displayed when a request for extracting data
            fails.
      description: Job result. If successful, contains the url, if failed, an error
        message is displayed.
    jobStatus:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the job.
          format: uuid
        status:
          type: string
          description: Job status that can be returned.
          example: SUCCEEDED
          enum:
          - RUNNING
          - SUCCEEDED
          - FAILED
          - CANCELLED
          - EXPIRED
        result:
          $ref: '#/components/schemas/jobResult'
      description: Job Status, includes job ID and job status.
    conditionField:
      type: object
      properties:
        dbName:
          type: string
          description: Name of the database which contains the primary table.
          example: data_lake
        tableName:
          type: string
          description: Name of primary table.
          example: refined_qm_evaluation
        columnName:
          type: string
          description: Name of the column used to filter the data.
          example: evaluation_date
      description: Filter data extraction request according to database, table name,
        and column name.
    conditions:
      required:
      - date
      - tenant
      type: object
      properties:
        tenant:
          $ref: '#/components/schemas/conditionField'
        date:
          $ref: '#/components/schemas/conditionField'
      description: Filter data extraction request by tenant and date.
    entityDetails:
      required:
      - conditions
      - join
      - tables
      type: object
      properties:
        tables:
          type: array
          description: Details of all tables from which to extract data, such as table
            name, database name where table is located, etc.
          items:
            $ref: '#/components/schemas/tableDetails'
        join:
          $ref: '#/components/schemas/join'
        conditions:
          $ref: '#/components/schemas/conditions'
        dateResolution:
          type: string
          description: Query partitions of the entity.
          enum:
          - day
          - month
          - year
      description: 'Details of an entity, which includes: a list of tables, a list
        of join parts, conditions, and date resolution.'
    entityResponse:
      type: object
      properties:
        entity:
          $ref: '#/components/schemas/entityDetails'
      description: Successful response.
    fieldDetails:
      type: object
      properties:
        displayName:
          type: string
          description: Display name of the column.
          example: Form Name
        columnName:
          type: string
          description: Column name in the table.
          example: form_name
      description: Field details.
    join:
      required:
      - parts
      type: object
      properties:
        dbName:
          type: string
          description: Name of database where the primary table is located.
          example: data_lake
        tableName:
          type: string
          description: Name of the primary table to use to create a joint table.
          example: refined_qm_evaluation
        parts:
          type: array
          description: List of parts used to join the primary table.
          items:
            $ref: '#/components/schemas/joinPart'
      description: Contains details needed to combine database tables.
    joinField:
      type: object
      properties:
        dbName:
          type: string
          description: Name of database where the table you want to join is located.
          example: data_lake
        tableName:
          type: string
          description: Name of the appending table that you want to combine with the
            primary table.
          example: refined_qm_evaluation
        joinedColumnName:
          type: string
          description: Column in the appending table that will join the primary table.
          example: user_uuid
        placeHolderType:
          type: string
          description: Name or fixed value of the column in the appending table that
            will join the primary table. Use the TENANT_ID to filter according to
            tenants.
          enum:
          - NO
          - FIXED
          - TENANT_ID
        columnName:
          type: string
          description: Name of the column in the primary table on which to base joining
            the tables.
          example: evaluator_id
      description: Join tables based on these fields.
    joinPart:
      required:
      - aliasSuffix
      - partFields
      - type
      type: object
      properties:
        dbName:
          type: string
          description: Name of database where the table is located.
          example: data_lake
        tableName:
          type: string
          description: Name of the table to join with the primary table.
          example: refined_userhub_user
        aliasSuffix:
          type: string
          description: Suffix added to create the table alias.
          example: EVALUATOR
        type:
          type: string
          description: Type of table combination used to create the joint table.
          enum:
          - LEFT
          - INNER
          - RIGHT
          - FULL
        partFields:
          type: array
          description: Fields to use when joining tables.
          items:
            $ref: '#/components/schemas/joinField'
      description: Details about the table that will join the primary table.
    tableDetails:
      required:
      - aliasSuffix
      - fields
      type: object
      properties:
        dbName:
          type: string
          description: Name of the database from which to extract data.
          example: data_lake
        tableName:
          type: string
          description: Name of the table from which to extract data.
          example: refined_userhub_user
        aliasSuffix:
          type: string
          description: Suffix added to create table alias.
          example: AGENT
        fields:
          type: array
          description: List of field details. Fields include the display name and
            the column name.
          items:
            $ref: '#/components/schemas/fieldDetails'
      description: Table details.
    entityInfoResponse:
      type: object
      properties:
        entityName:
          type: string
          description: Name of the entity that was added.
          example: qm-workflows
        entityVersion:
          type: string
          description: Version of the entity that was added.
          example: "1"
      description: Successful response returned.
    addEntityRequest:
      required:
      - entity
      type: object
      properties:
        entityName:
          type: string
          description: Name of entity to add.
        entity:
          $ref: '#/components/schemas/entityDetails'
        licenses:
          type: array
          description: List of licenses needed to use the entity that you are adding.
          example:
          - QM
          - WFM
          items:
            type: string
            description: List of licenses needed to use the entity that you are adding.
            example: '["QM","WFM"]'
        permissions:
          type: array
          description: Permissions needed to use the entity that you are adding.
          example:
          - performancemonitoring:View
          - agentList:View
          items:
            type: string
            description: Permissions needed to use the entity that you are adding.
            example: '["performancemonitoring:View","agentList:View"]'
        featureToggle:
          type: string
          description: Name of the feature toggle you need to turn on in order to
            use the entity you are adding.
          example: qm-data-extraction
      description: Parameters that needed for request to add a new entity.
    entityPackResponse:
      type: object
      properties:
        name:
          type: string
          description: Name of the entity that was updated.
          example: qm-workflows
        version:
          type: string
          description: Version of the entity that was updated.
          example: "3"
        entity:
          $ref: '#/components/schemas/entityDetails'
        licenses:
          type: array
          description: A modified list of entity licenses needed to use the entity
            that was updated.
          example:
          - QM
          items:
            type: string
            description: A modified list of entity licenses needed to use the entity
              that was updated.
            example: '["QM"]'
        permissions:
          type: array
          description: A modified list of permissions needed to use the entity that
            was updated.
          example:
          - performancemonitoring:View
          items:
            type: string
            description: A modified list of permissions needed to use the entity that
              was updated.
            example: '["performancemonitoring:View"]'
        featureToggle:
          type: string
          description: Feature toggle for using the entity that was updated.
          example: qm-data-extraction
      description: Successful entity update.
    updateEntityRequest:
      type: object
      properties:
        entityName:
          type: string
          description: Name of the entity to update.
        licenses:
          type: array
          description: A modified list of entity licenses needed to access the entity
            you are updating.
          example: QM
          items:
            type: string
            description: A modified list of entity licenses needed to access the entity
              you are updating.
            example: QM
        permissions:
          type: array
          description: A modified list of permissions needed to access the entity
            that you are updating.
          example: agentList:View
          items:
            type: string
            description: A modified list of permissions needed to access the entity
              that you are updating.
            example: agentList:View
        featureToggle:
          type: string
          description: Feature toggle for accessing the entity to update.
          example: qm-data-extraction
      description: Request to update an existing entity.
    entityDescriptionResponse:
      type: object
      properties:
        name:
          type: string
          description: Name of the entity that was updated.
          example: qm-workflows
        version:
          type: integer
          description: Version of the entity that was updated.
          format: int32
          example: 3
        fieldsList:
          type: array
          description: A modified list of entity's fields.
          example:
          - Master Contact
          - Segment
          - Direction
          items:
            type: string
            description: A modified list of entity's fields.
            example: '["Master Contact","Segment","Direction"]'
      description: Successful get entity description.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT