openapi: 3.0.0
info:
  title: Clari API Reference Activity API Forecast API API
  version: 5.0.0
  description: "# Clari API Reference\nClari is the heartbeat of your revenue organization and holds your most important revenue data. Clari APIs enable customers to retrieve revenue data out of the Clari platform and push missing revenue-critical data into the platform.\n\n## Authentication\n\nClari APIs use tokens to authenticate requests. You can create and manage your tokens in Account Settings under \"API Token\". Please reach out to your CSM if you don't see a token generation tool as you may not have been given access.\n### Creating an authentication token\nFollow the steps below to generate a token:\n- Go to user avatar\n- Navigate to Settings\n- Navigate to the API Token tab and click \"Generate New API Token\"\n- Enter a Token Name and click \"Generate New Token\". Few things to note about tokens:\n  - After generating a token, make sure to keep it in a secure location as you won't be able to access it again. This is your key to accessing Clari data for your organization.\n  - If you revoke a token, any active integration that is using that token will break.\n  - When deactivating a user, any tokens created by the user will be revoked (and thus break any active integration).\n\n## Bulk data exports\n\nClari supports bulk data exports. Bulk exports run asynchronously in a\nthree step process. First, the bulk export is requested using a `POST` API call.\nMultiple products support bulk exports. In the documentation below, the `POST` API\nis described in respective product sections. The `POST` API call queues the bulk export job to run it asynchronously, and returns\na job ID. To monitor the export's status and be notified of its completion, you\nshould poll status via the API periodically. When the export completes, the status\nwill be set to `DONE` and you can then retrieve the output of the export.\n\n## Bulk data imports\n\nClari also supports bulk data imports. Customers or partners can import their Account\nor Opportunity fields in bulk to create a complete picture of revenue in Clari. Bulk imports also run\nasynchronously in a three step process. In the documentation below, the `/bulk` API is described\nin respective product sections. The `/bulk` API call queues the bulk import job to run it asynchronously, and returns\na job ID. To monitor the import's status and be notified of its completion, you\nshould poll status via the API periodically. When the import completes, the status\nwill be set to `DONE`. If records fail validation, the entire batch is rejected and has to be retried\nafter fixing the errors. The errors can be retrieved from the results API.\n\n\n## Forecasting APIs\n\nRevenue teams use Clari Forecasting to track their attainment to date\nagainst goals and forecast their revenue numbers for the month, quarter and\nyear. This data is captured by revenue leaders, managers, and sales reps --\nit provides a clear view of the entire team's forecast and their submission\nstatus.\n\nClari's Forecasting APIs enable you to pull your forecasting data out of Clari, merge\nit with data sitting in your own data warehouse, and build custom reports. Forecasting\nsupports both a REST API as well as a bulk export API.\n\n### Creating and accessing Forecast exports\n\n\n  You can export any Forecast Tab with our Forecasting APIs. To do so, retrieve the `forecastId` from the URL when viewing a Forecast Tab and provide the ID when using the Export API. If you don't already have a Forecast Tab configured for the data you're trying to export, please work with your CSM to get that configured first.\n\n  <img src=\"https://developer.clari.com/assets/images/forecastid.png\" alt=\"forecast id\" width=\"400\"/>\n\n\nFor details on Forecast Tabs and what data is available with Forecast Exports see guides below:\n\n- [Forecasting Building Blocks](https://clari.my.site.com/customer/s/article/Forecast-Building-Blocks)\n- [How to Read the Forecast Export](https://clari.my.site.com/customer/s/article/How-to-Read-the-Forecast-Export)\n- [How to Read the Export API Output](https://clari.my.site.com/customer/s/article/How-to-Read-Claris-Export-API-Output)\n\n\n## Audit APIs\n\nThe Audit API allows its users to audit events happening in their Clari instances. Call the Audit API to understand who is making changes in your Clari instance and when these changes happened.\n\n## Data Ingestion API\n\nThis API is for Clari's integration partners - such as technology platforms or revenue tools, looking to build a direct data integration with Clari. It enables partners to send data that can be surfaced in Clari's Accounts and Opportunities views for mutual customers who have turned on the integration.\n\n## Activity API\n\nActivity Export API allows its users to pull sales activity data like emails, meetings and files.\nWith this powerful sales activity data available on demand through an API call, customers can create powerful custom reports in the reporting tool of their choice and analyze Accounts and Opportunity engagement across different activity types.\n\n## Questions?\n"
  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: Forecast API
paths:
  /export/forecast/{forecastId}:
    post:
      summary: Create a new forecast export
      description: 'Configure and start processing an export job by providing the ID of the Forecast Tab you would like to export data from. You will be able to retrieve the `forecastId` from the URL when viewing a Forecast Tab from your Clari account. If you don''t already have a Forecast Tab configured for the data you''re trying to export, please work with your CSM to get that configured first.


        To create your request, you will need to pass your `apikey` in as a header, the `forecastId` in the request path, and all other optional parameters as a JSON in the body.'
      operationId: externalFcwExport
      tags:
      - Forecast API
      parameters:
      - name: apikey
        in: header
        description: Authentication token.
        required: true
        schema:
          type: string
      - name: forecastId
        in: path
        description: Forecast tab on which to run the export on.
        required: true
        schema:
          type: string
      - name: timePeriod
        in: query
        description: 'Fiscal Quarter for when you''d like to run your export. Must be passed in as a string (e.g. "YYYY_QQ")


          <img src="https://developer.clari.com/assets/images/fiscal_quarter.png" alt="fiscal quarter" width="300"/>'
        schema:
          type: string
          example: 2020_Q3
          default: current quarter
      - name: scopeId
        in: query
        description: Specifies the scopeId to use as the root for the hierarchy that the export will run against. We recommend to add the integration user at the top of the hierarchy and opting the integration user into forecasting.
        schema:
          type: string
          example: 1905::MGR
          default: null
      - name: typesToExport
        in: query
        description: 'Forecast data types you''d like to export. Must be passed in as a list.

          - **forecast** indicates the actual amount entered by the individual contributor, and is associated with the forecast call fields (i.e. Commit or Most Likely, Best Case or Upside, etc.).

          - **quota** indicates the value from the Quota field in Forecasting, and this data type is associated with Quota fields (i.e. Quota, Plan, Budget, etc.).

          - **forecast_updated** indicates whether or not the individual contributor actually went into Forecasting and updated their call(s) or number(s), and this data type is associated with forecast call fields.

          - **adjustment** indicates the adjusted call/number that a forecasting manager entered when they made a manager override to their report''s call/number, and this data type is associated with forecast call fields.

          - **crm_total** indicates the crm aggregation value for an associated field and owner is desired for the fields returned in the payload.

          - **crm_closed** indicates the opportunities closed amount.'
        schema:
          type: array
          items:
            enum:
            - forecast
            - quota
            - forecast_updated
            - adjustment
            - crm_total
            - crm_closed
            type: string
          example: forecast
          default: forecast *AND* forecast_updated
      - name: currency
        in: query
        description: Specifies the currency that currency fields should return in.
        schema:
          type: string
          example: USD
          default: null
      - name: exportFormat
        in: query
        description: Format of the exported file. Some export formats can be unavailable depending the export data size and type.
        schema:
          type: string
          enum:
          - CSV
          - JSON
          example: CSV
          default: JSON
      - name: includeHistorical
        in: query
        description: If set to true, you will receive week over week forecasts and CRM aggregations from the start of the quarter requested in timePeriod till the current week.  If false, only the current week’s forecast and CRM aggregations will be returned…
        schema:
          type: boolean
          example: true
      requestBody:
        description: Optional request parameters for the forecast export.
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                timePeriod:
                  type: string
                  description: Fiscal quarter for when you'd like to run your export. Must be passed in as a string (e.g. "YYYY_QQ")
                  example: 2020_Q3
                  default: current quarter
                typesToExport:
                  description: "Forecast data types you'd like to export. Must be passed in as a list of strings.\n      \n- `forecast` indicates the actual amount entered by the individual contributor, and is associated with the forecast call fields (i.e. Commit or Most Likely, Best Case or Upside, etc.).\n- `quota` indicates the value from the Quota field in Forecasting, and this data type is associated with Quota fields (i.e. Quota, Plan, Budget, etc.).\n- `forecast_updated` indicates whether or not the individual contributor actually went into Forecasting and updated their call(s) or number(s), and this data type is associated with forecast call fields.  \n- `adjustment` indicates the adjusted call/number that a forecasting manager entered when they made a manager override to their report's call/number, and this data type is associated with forecast call fields.\n- `crm_total` indicates the Opportunities Total, and this data type is associated with read only fields.\n- `crm_closed` indicates the opportunities closed amount."
                  type: array
                  items:
                    enum:
                    - forecast
                    - quota
                    - forecast_updated
                    - adjustment
                    - crm_total
                    - crm_closed
                    type: string
                  example:
                  - forecast
                  - forecast_updated
                  default:
                  - forecast
                  - forecast_updated
                scopeId:
                  type: string
                  description: Specifies the scopeId to use as the root for the hierarchy that the export will run against.
                  example: 1905::MGR
                  default: null
                currency:
                  type: string
                  description: Specifies the currency that currency fields should return in.
                  example: USD
                  default: null
                schedule:
                  description: 'Use this parameter to schedule retries of your export if the first attempt fails.

                    - `NONE` means no retries

                    - `ONCE` means retry once after 30 minutes if the first attempt failed

                    - `MAX` means retry 3 times with 30 minute sleep between failed runs

                    '
                  type: string
                  enum:
                  - NONE
                  - ONCE
                  - MAX
                  default: NONE
                includeHistorical:
                  type: boolean
                  description: 'If set to true, you will receive week over week forecasts from the start of the quarter requested in `timePeriod` till the current week. If false, only the current week’s forecast will be returned. Note: these weeks will not be ordered by default in the JSON response. You can sort on the `timeFrameId` to sequence the weeks as needed.'
                  default: false
                exportFormat:
                  type: string
                  enum:
                  - JSON
                  - CSV
                  description: Format of the exported file
                  example: CSV
                  default: JSON
      responses:
        '200':
          description: Your export job was successfully queued. Use the `jobId`, provided in your response, to check it's status and retrieve the requested data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobId:
                    type: string
                    description: Unique identifier for your forecast export request. Use this `jobId` to check the status and retrieve data for your export.
              example:
                jobId: 6073683781a6da229df71e00
        '400':
          description: Your job could not be queued. You may have reached your monthly quota or concurrent job limit. Use the `/admin/limits` endpoint to find out which limit you have hit. If you find yourself hitting the concurrent limit often, try adjusting your request parameters. Specifically, set `SCHEDULE` to `ONCE` or `MAX`. This parameter will initiate retries without extra effort on your end.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/paths/~1export~1activity/post/responses/400/content/application~1json/schema/oneOf/1'
                - description: An exception thrown when a forecast is requested that does not exist.
                  type: object
                  properties:
                    code:
                      type: string
                      example: no_such_forecast_config
                    namespace:
                      type: string
                      example: fcw
                    errorId:
                      type: string
                      example: c16ae643-481a-11eb-a48d-a7e5677deee5
                    message:
                      type: string
                      example: Forecast deal_owner does not exist in the ForecastTemplate.
                    orgId:
                      $ref: '#/paths/~1export~1activity/post/responses/500/content/application~1json/schema/properties/orgId'
                - description: An exception thrown when a the forecast path parameter is not present.
                  type: object
                  properties:
                    code:
                      type: string
                      example: missing_forecast_id
                    namespace:
                      type: string
                      example: fcw
                    errorId:
                      type: string
                      example: c16ae643-481a-11eb-a48d-a7e5677deee5
                    message:
                      type: string
                      example: The forecastId query parameter is required.
                    orgId:
                      $ref: '#/paths/~1export~1activity/post/responses/500/content/application~1json/schema/properties/orgId'
                - description: An exception thrown when a forecast export request is made with an unsupported typeToExport.
                  type: object
                  properties:
                    code:
                      type: string
                      example: type_not_supported
                    namespace:
                      type: string
                      example: fcw
                    errorId:
                      type: string
                      example: c16ae643-481a-11eb-a48d-a7e5677deee5
                    message:
                      type: string
                      example: CRM Totals and CRM Closed are not supported typeToExport values for Export API. Please see Forecast API documentation if you’d like to retrieve CRM Totals or CRM Closed values.
                    orgId:
                      $ref: '#/paths/~1export~1activity/post/responses/500/content/application~1json/schema/properties/orgId'
                - description: An exception thrown when the request body is malformed.
                  type: object
                  properties:
                    code:
                      type: string
                      example: bad_request
                    namespace:
                      type: string
                      example: fcw
                    errorId:
                      type: string
                      example: c16ae643-481a-11eb-a48d-a7e5677deee5
                    message:
                      type: string
                      example: 'The request body was malformed: {REQUEST_BODY}'
                    orgId:
                      $ref: '#/paths/~1export~1activity/post/responses/500/content/application~1json/schema/properties/orgId'
                - description: An exception thrown when the currency query parameter is not valid.
                  type: object
                  properties:
                    code:
                      type: string
                      example: bad_request
                    namespace:
                      type: string
                      example: fcw
                    errorId:
                      type: string
                      example: c16ae643-481a-11eb-a48d-a7e5677deee5
                    message:
                      type: string
                      example: The currency parameter is invalid.
                    orgId:
                      $ref: '#/paths/~1export~1activity/post/responses/500/content/application~1json/schema/properties/orgId'
                - description: An exception thrown when a typesToExport query parameter is not valid.
                  type: object
                  properties:
                    code:
                      type: string
                      example: bad_request
                    namespace:
                      type: string
                      example: fcw
                    errorId:
                      type: string
                      example: c16ae643-481a-11eb-a48d-a7e5677deee5
                    message:
                      type: string
                      example: 'The following typesToExport values are invalid: ["forecast_value", "quota_value"]'
                    orgId:
                      $ref: '#/paths/~1export~1activity/post/responses/500/content/application~1json/schema/properties/orgId'
        '401':
          description: The user associated with the api token does not have permission to view the requested forecast's data.
          content:
            application/json:
              schema:
                description: An exception thrown when access to a given forecast is not allowed for the user.
                type: object
                properties:
                  code:
                    type: string
                    example: no_optin
                  namespace:
                    type: string
                    example: fcw
                  errorId:
                    type: string
                    example: c16ae643-481a-11eb-a48d-a7e5677deee5
                  message:
                    type: string
                    example: No optins for scope 1::MGR for forecast 'deal_owner'.
                  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'
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: apikey
      in: header