Clari Bulk Export Framework API

openapi: 3.2.0
info:
  title: Clari API Reference Bulk Export Framework API
  version: 5.0.0
  description: '# Clari API Reference

    Clari is the heartbeat of your revenue organization and holds your most important revenue data.'
  contact:
    name: us here! We're always happy to help with any questions.
    email: support@clari.com
servers:
- url: https://api.clari.com/{basePath}
  description: Clari gateway
  variables:
    basePath:
      default: v4
      description: version identifier
security:
- api_key: []
tags:
- name: Bulk Export Framework
paths:
  /export/jobs/{jobId}:
    get:
      summary: View the status of a given export using its jobId
      description: 'Once your export job has been successfully created, it will be initialized with `"status": "STARTED"`. You''ll need to poll the status of your request until it is complete. The possible states of your export request are:

        - `SCHEDULED` - job successfully created and queued up

        - `STARTED` - job in-progress

        - `DONE` - job complete and ready to output data

        - `FAILED` - job could not complete

        - `CANCELLED` - job was scheduled but then got cancelled

        - `ABORTED` - job started running but then got cancelled'
      operationId: jobStatus
      tags:
      - Bulk Export Framework
      parameters:
      - name: apikey
        in: header
        description: Authentication token.
        required: true
        schema:
          type: string
      - name: jobId
        description: The job id for the job to fetch the details for.
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success! See job details for the requested job ID.
          content:
            application/json:
              schema:
                description: The UI formatted export item.
                type: object
                properties:
                  jobId:
                    type: string
                    description: Unique identifier for your forecast export request.
                    example: 6073683781a6da229df71e00
                  userId:
                    type: integer
                    description: Clari user ID of the user that initiated the job.
                    example: 1
                  orgId:
                    type: integer
                    description: Clari org ID of the user that requested the job.
                    example: 101
                  title:
                    type: string
                    description: Title of the Forecast Tab requested for the export.
                    example: Forecast Export
                  module:
                    type: string
                    description: Module from which the export is requested from.
                    example: FORECAST
                  startTime:
                    type: integer
                    description: Start time of export job.
                    example: 1618451575216
                  endTime:
                    type: integer
                    description: End time of export job.
                    example: 1618451581663
                  expiredTime:
                    type: integer
                    description: Expiry time of export job.
                    example: 1621043581663
                  version:
                    type: integer
                    description: API version from when export job was initiated.
                    example: 1
                  fileName:
                    type: string
                    description: File name of export job.
                    example: clari_export_forecast_total_new_2021_Q12915_20210415_015255.json
                  fileType:
                    type: string
                    example: JSON
                  status:
                    description: The status of the export job.
                    type: string
                    enum:
                    - SCHEDULED
                    - STARTED
                    - DONE
                    - FAILED
                    - CANCELLED
                    - ABORTED
                  viewed:
                    type: boolean
                    example: false
                  cellsTruncated:
                    type: boolean
                    example: false
                  rowsTruncated:
                    type: boolean
                    example: false
                  downloads:
                    type: integer
                    description: Number of times the export request was downloaded.
                    example: 1
                  currency:
                    type: string
                    description: Currency used when initiating export job.
                    example: USD
              example:
                jobId: 606e23c981a6da229d75b515
                userId: 1
                orgId: 101
                title: Forecast Export
                module: FORECAST
                startTime: 1617830857175
                endTime: 1617830861959
                expiredTime: 1620422861959
                version: 1
                fileName: clari_export_forecast_new_summary_2021_Q12915_20210407_212737.json
                fileType: JSON
                status: STARTED
                viewed: false
                cellsTruncated: false
                rowsTruncated: false
                downloads: 0
                deliveryStatusMap: {}
                currency: USD
        '400':
          description: The job status could not be retrieved.
          content:
            application/json:
              schema:
                $ref: '#/paths/~1export~1jobs/get/responses/400/content/application~1json/schema'
        '403':
          description: Invalid permissions to view this job.
          content:
            application/json:
              schema:
                $ref: '#/paths/~1export~1jobs/get/responses/400/content/application~1json/schema'
        '500':
          description: There was an unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/paths/~1export~1activity/post/responses/500/content/application~1json/schema'
    patch:
      summary: Stop or cancel an in-progress job
      description: Use this endpoint to stop or “cancel” an in-progress export job. The job will stop executing and free up space on your monthly quota. The job will still be accessible if you call the `GET /export/jobs` endpoint.
      operationId: updateJob
      tags:
      - Bulk Export Framework
      parameters:
      - name: apikey
        in: header
        description: Authentication token.
        required: true
        schema:
          type: string
      - name: jobId
        description: The job id for the job to fetch the details for.
        $ref: '#/paths/~1export~1jobs~1%7BjobId%7D/get/parameters/1'
      requestBody:
        description: The request parameters for the update options available to update the job with.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  description: The type of patch task to perform on the job. Currently only `CANCEL` is supported.
                  type: string
                  example: CANCEL
                  enum:
                  - CANCEL
      responses:
        '200':
          description: Your job was successfully cancelled.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    $ref: '#/paths/~1export~1jobs~1%7BjobId%7D/get/responses/200/content/application~1json/schema/properties/status'
                  successful:
                    type: boolean
                example:
                  status: CANCELLED
                  successful: true
        '400':
          description: Unable to complete request. Please check your parameters and/or the status of your job. If the job has already completed where `STATUS` is `DONE` you will not be able to cancel it.
          content:
            application/json:
              schema:
                description: Cannot cancel job as it has already finished executing.
                type: object
                properties:
                  code:
                    type: string
                    example: export_failed_to_cancel
                  namespace:
                    type: string
                    example: exports
                  errorId:
                    type: string
                    example: 54c5a2b5-9b1c-11eb-a343-87ffa5f01191
                  message:
                    type: string
                    example: Cannot cancel the job because it already finished executing.
                  orgId:
                    $ref: '#/paths/~1export~1activity/post/responses/500/content/application~1json/schema/properties/orgId'
        '500':
          description: There was an unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/paths/~1export~1activity/post/responses/500/content/application~1json/schema'
  /export/jobs/{jobId}/results:
    get:
      summary: Retrieve and save forecast export content
      description: Once your export finishes processing and its status returns `DONE`, you will be able to retrieve your file contents using this endpoint.
      operationId: externalExportDownload
      tags:
      - Bulk Export Framework
      parameters:
      - name: apikey
        in: header
        description: Authentication token.
        required: true
        schema:
          type: string
      - name: jobId
        description: The job ID for the export job to fetch JSON output for.
        $ref: '#/paths/~1export~1jobs~1%7BjobId%7D/get/parameters/1'
      responses:
        '200':
          description: Retrieve the content of the output file of the desired export job.
          content:
            application/json:
              example:
              - User
              - Email
              - CRM User ID
              - Role
              - Parent Role
              - Timeframe
              - Field
              - Week
              - Start Day
              - End Day
              - Data Type
              - Data Value
              - Jain
              - name@s-clari.com
              - 005110000069tRpAAI
              - Sales Rep - East
              - CEO
              - July FY 2023
              - Monthly Commit
              - '0'
              - 06/30/2023
              - 06/30/2023
              - Forecast Value
              - Jain
              - name@s-clari.com
              - 005110000069tRpAAI
              - Sales Rep - East
              - CEO
              - July FY 2023
              - Monthly Commit
              - '0'
              - 06/30/2023
              - 06/30/2023
              - Forecast Updated
              - 'No'
              - Clari QA10
              - manager@s-clari.com
              - 005d0000001rfYSAAY
              - CEO
              - ''
              - July FY 2023
              - Monthly Commit
              - '0'
              - 06/30/2023
              - 06/30/2023
              - Forecast Value
              - $3,000,190.00
              - Clari QA10
              - manager@s-clari.com
              - 005d0000001rfYSAAY
              - CEO
              - ''
              - July FY 2023
              - Monthly Commit
              - '0'
              - 06/30/2023
              - 06/30/2023
              - Forecast Updated
              - 'No'
        '400':
          description: Unable to retrieve data. Please ensure you have passed in a valid `jobId`. Note that you will only be able to retrieve output for successfully completed jobs. Specifically, the job's status must be `DONE` in order to retrieve its output.
          content:
            application/json:
              schema:
                description: Cannot retrieve data for the requested jobId. Check your parameters and try again.
                type: object
                properties:
                  code:
                    type: string
                    example: invalid_jobId
                  namespace:
                    type: string
                    example: exports
                  errorId:
                    type: string
                    example: 54c5a2b5-9b1c-11eb-a343-87ffa5f01191
                  message:
                    type: string
                    example: Cannot retrieve data for job because it has not finished executing.
                  orgId:
                    $ref: '#/paths/~1export~1activity/post/responses/500/content/application~1json/schema/properties/orgId'
        '500':
          description: There was an unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/paths/~1export~1activity/post/responses/500/content/application~1json/schema'
  /export/jobs:
    get:
      summary: View all jobs initiated from a particular user
      description: View a list of all jobs initiated by a particular user. The response will include all complete, cancelled, and in-progress jobs.
      operationId: externalFcwExport
      parameters:
      - name: apikey
        in: header
        description: Authentication token.
        required: true
        schema:
          type: string
      tags:
      - Bulk Export Framework
      responses:
        '200':
          description: Success! See job details for all export jobs initiated by the authentication token passed in your parameter.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/paths/~1export~1jobs~1%7BjobId%7D/get/responses/200/content/application~1json/schema'
              example:
              - jobId: 6073683781a6da229df71e00,
                userId: 1,
                orgId: 1,
                title: Forecast Export,
                module: FORECAST,
                startTime: 123456789,
                endTime: 123456799,
                expiredTime: 133333333,
                version: 1,
                fileName: clari_export_default-view_20180118_004234.json,
                fileType: JSON,
                status: STARTED,
                viewed: true,
                cellsTruncated: false,
                rowsTruncated: false,
                downloads: 0,
                currency: USD
              - jobId: 6073680cac043e61f93bac07,
                userId: 1,
                orgId: 1,
                title: Forecast Export,
                module: FORECAST,
                startTime: 133456789,
                endTime: 133456799,
                expiredTime: 143333333,
                version: 1,
                fileName: clari_export_default-view_20180118_004234.json,
                fileType: JSON,
                status: STARTED,
                viewed: true,
                cellsTruncated: false,
                rowsTruncated: false,
                downloads: 2,
                currency: USD
        '400':
          description: The job status could not be retrieved.
          content:
            application/json:
              schema:
                description: The generic exception response from the application.
                type: object
                properties:
                  code:
                    type: string
                    example: SWW
                  namespace:
                    type: string
                    example: exports
                  errorId:
                    type: string
                    example: c16ae643-481a-11eb-a48d-a7e5677deee5
                  message:
                    type: string
                    example: Something went wrong
                  orgId:
                    $ref: '#/paths/~1export~1activity/post/responses/500/content/application~1json/schema/properties/orgId'
        '403':
          description: Invalid permissions to view this job.
          content:
            application/json:
              schema:
                $ref: '#/paths/~1export~1jobs/get/responses/400/content/application~1json/schema'
        '500':
          description: There was an unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/paths/~1export~1activity/post/responses/500/content/application~1json/schema'
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: apikey
      in: header