---
updatedAt: 2026-09-03T16:37:06.000Z
agentTools:
  projectIndex: https://docs.talkdesk.com/llms.txt
---

# WFM Forecast Import API

</style>

</head>
<body>

  <h1>WFM Forecast Import API</h1>

  <div class="toc">
    <div class="toc-title">On this page</div>
    <ol>
      <li><a href="#overview">Overview</a></li>
      <li><a href="#business-context">Business Problem-Solving Context</a></li>
      <li><a href="#use-case">Use Case</a></li>
      <li><a href="#usage">Usage</a>
        <ol>
          <li><a href="#post-forecast-imports">POST /forecast_imports</a></li>
          <li><a href="#get-forecast-imports">GET /forecast_imports/{import_id}</a></li>
        </ol>
      </li>
      <li><a href="#csv-format">CSV File Format</a></li>
      <li><a href="#auth">Authentication &amp; Authorization</a></li>
      <li><a href="#limits">Subscription Limits</a></li>
    </ol>
  </div>

  <h2 id="overview">Overview</h2>

  <p>The Workforce Management (WFM) Forecast Import API allows customers to programmatically upload forecast data into Talkdesk Workforce Management via CSV files. This API is part of the <strong>Talkdesk Workforce Management</strong> product.</p>

  <p>Typical use cases include:</p>

  <ul>
    <li>Importing externally generated forecast data (e.g., from third-party WFM or BI tools) into Talkdesk WFM.</li>
    <li>Overriding system-generated forecasts with manually adjusted values for specific queues and time intervals.</li>
    <li>Automating periodic forecast uploads as part of a workforce planning pipeline.</li>
  </ul>

  <hr class="divider" />

  <h2 id="business-context">Business Problem-Solving Context</h2>

  <h3>What can I achieve with this API?</h3>

  <ul>
    <li><strong>Upload forecast data via CSV:</strong> Submit a CSV file containing forecast metrics (interaction volume, average handle time, shrinkage) for one or more queues across configurable time intervals.</li>
    <li><strong>Track import status:</strong> Poll the import status by ID to monitor progress and retrieve error details including a downloadable error report.</li>
  </ul>

  <h3>What business problems does this API solve?</h3>

  <ul>
    <li><strong>Third-party forecast integration:</strong> Organizations that use external forecasting tools or statistical models can push their forecast data into Talkdesk WFM without manual data entry in the UI.</li>
    <li><strong>Bulk forecast overrides:</strong> Supervisors and planners who need to adjust forecast values across multiple queues and time periods can prepare changes in a spreadsheet and upload them in a single operation rather than editing each interval individually.</li>
    <li><strong>Automated planning workflows:</strong> Enterprises with mature planning processes can integrate forecast uploads into their automated workflows (e.g., nightly batch jobs that generate forecasts from external data sources and push them into Talkdesk WFM).</li>
  </ul>

  <h3>What does this API support and what are its limitations?</h3>

  <div class="panel panel-warning">
    <strong>Limitations</strong>
    <ul style="margin:0; padding-left:20px;">
      <li>Only one import per account can be in progress at any time. Attempting a second concurrent upload returns a <code>409 Conflict</code> error.</li>
      <li>The CSV file must use specific column headers: <code>Queue</code>, <code>Datetime</code>, <code>Interaction volume offered</code>, <code>Average handle time</code>, and optionally <code>Shrinkage</code>.</li>
      <li>Queue names in the CSV must match existing active queues configured in Talkdesk WFM.</li>
      <li>Datetime values must align with the specified <code>interval_editing</code> granularity (15 minutes, 30 minutes, or 1 hour).</li>
      <li>The error file download URL (for imports with partial errors) is valid for <strong>10 minutes</strong> after generation.</li>
    </ul>
  </div>

  <hr class="divider" />

  <h2 id="use-case">Use Case</h2>

  <h3>Importing forecast data from an external planning tool</h3>

  <p>A workforce planner generates a weekly forecast using a third-party analytics platform. The planner exports the forecast as a CSV file with the required columns and uploads it via the API:</p>

  <ul>
    <li>Upload the CSV using <code>POST /forecast_imports</code> with the forecast file, specifying the date format, timezone, and interval granularity.</li>
    <li>The response returns the <code>id</code>. Use it to poll the status via <code>GET /forecast_imports/{import_id}</code> until the import reaches a final state.</li>
    <li>If the status is <code>IMPORTED_WITH_ERRORS</code>, download the error report CSV from the <code>error_file_url</code> to review which rows failed validation and why.</li>
  </ul>

  <hr class="divider" />

  <h2 id="usage">Usage</h2>

  <p class="section-intro">The Forecast Import API provides two endpoints:</p>

  <ul>
    <li><strong>POST /forecast_imports</strong> — Upload a forecast CSV file</li>
    <li><strong>GET /forecast_imports/{import_id}</strong> — Retrieve the import status by ID</li>
  </ul>

  <h3 id="post-forecast-imports">POST /forecast_imports</h3>

  <div class="endpoint"><span class="method method-post">POST</span>/forecast_imports</div>

  <p>Upload a forecast CSV file for the account. Returns the import ID and status in the response body and the URL for tracking import status in the <code>Content-Location</code> header.</p>

  <p><strong>Content-Type:</strong> <code>multipart/form-data</code></p>

  <h3>Request Parameters (form data)</h3>

  <div class="table-wrap">

| Parameter                            | Type    | Required                                  | Default                 | Description                                                                                                      |
| ------------------------------------ | ------- | ----------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
| <code>csv\_file</code>               | binary  | <span class="badge badge-blue">Yes</span> | —                       | The CSV file to upload                                                                                           |
| <code>file\_name</code>              | string  | <span class="badge badge-blue">Yes</span> | —                       | The original file name including the <code>.csv</code> extension (max 255 characters)                            |
| <code>time\_zone</code>              | string  | <span class="badge badge-blue">Yes</span> | —                       | IANA time zone of the datetime values in the CSV (e.g., <code>America/New\_York</code>, max 64 characters)       |
| <code>date\_format</code>            | string  | No                                        | <code>DD/MM/YYYY</code> | Date format used in the Datetime column (e.g., <code>MM/DD/YYYY</code>, max 32 characters)                       |
| <code>interval\_editing</code>       | string  | No                                        | <code>MIN\_15</code>    | Interval granularity for forecast editing. Values: <code>MIN\_15</code>, <code>MIN\_30</code>, <code>HOUR</code> |
| <code>trigger\_scheduler\_job</code> | boolean | No                                        | <code>false</code>      | Whether to trigger the scheduler job after the import completes                                                  |

  </div>

  <h3>Response: 202 Accepted</h3>

  <pre>{
  "id": "8ae6a6b17c6fcc00017c6fddd2c00001",
  "status": "UPLOADED"
}</pre>

  <h3>Response Headers</h3>

  <div class="table-wrap">

| Header                        | Description                    |
| ----------------------------- | ------------------------------ |
| <code>Content-Location</code> | URL to check the import status |

  </div>

  <h3>Error Responses</h3>

  <div class="table-wrap">

| HTTP Status      | Description                                                        | Example Message                                                                                                    |
| ---------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| <code>400</code> | Bad Request — invalid CSV header or date format                    | Invalid CSV header. Expected headers: Queue, Datetime, Interaction volume offered, Average handle time, Shrinkage. |
| <code>401</code> | Unauthorized                                                       | Authentication credentials are missing or invalid.                                                                 |
| <code>403</code> | Forbidden                                                          | Insufficient permissions to perform this operation.                                                                |
| <code>409</code> | Conflict — a forecast import is already in progress                | A forecast import is already in progress for this account.                                                         |
| <code>413</code> | Payload Too Large                                                  | The uploaded file exceeds the maximum allowed size.                                                                |
| <code>415</code> | Unsupported Media Type — only <code>.csv</code> files are accepted | Only .csv files are accepted.                                                                                      |
| <code>429</code> | Too Many Requests                                                  | Rate limit exceeded. Please retry later.                                                                           |

  </div>

  <h3 id="get-forecast-imports">GET /forecast_imports/{import_id}</h3>

  <div class="endpoint"><span class="method method-get">GET</span>/forecast_imports/{import_id}</div>

  <p>Retrieve the current status of a Forecast Import by its ID.</p>

  <h3>Path Parameters</h3>

  <div class="table-wrap">

| Parameter               | Type   | Required                                  | Description                                  |
| ----------------------- | ------ | ----------------------------------------- | -------------------------------------------- |
| <code>import\_id</code> | string | <span class="badge badge-blue">Yes</span> | The unique identifier of the forecast import |

  </div>

  <h3>Response: 200 OK</h3>

  <p><strong>Success example:</strong></p>

  <pre>{
  "id": "8ae6a6b17c6fcc00017c6fddd2c00001",
  "status": "IMPORTED",
  "created_at": "2026-05-20T10:30:00Z",
  "updated_at": "2026-05-20T10:35:00Z",
  "error_file_url": null
}</pre>

  <p><strong>With errors example:</strong></p>

  <pre>{
  "id": "8ae6a6b17c6fcc00017c6fddd2c00001",
  "status": "IMPORTED_WITH_ERRORS",
  "created_at": "2026-05-20T10:30:00Z",
  "updated_at": "2026-05-20T10:35:00Z",
  "error_file_url": "https://s3.amazonaws.com/bucket/errors.csv?X-Amz-Expires=600"
}</pre>

  <h3>Response Fields</h3>

  <div class="table-wrap">

| Field                         | Type               | Required                                  | Description                                                                                                                                                   |
| ----------------------------- | ------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <code>id</code>               | string             | <span class="badge badge-blue">Yes</span> | The unique identifier of the import                                                                                                                           |
| <code>status</code>           | string             | <span class="badge badge-blue">Yes</span> | The current processing status                                                                                                                                 |
| <code>created\_at</code>      | string (date-time) | <span class="badge badge-blue">Yes</span> | When the import was created                                                                                                                                   |
| <code>updated\_at</code>      | string (date-time) | <span class="badge badge-blue">Yes</span> | When the import was last updated                                                                                                                              |
| <code>error\_file\_url</code> | string (nullable)  | No                                        | Pre-signed URL to download the error report CSV. Present only when status is <code>IMPORTED\_WITH\_ERRORS</code> or <code>ERROR</code>. Valid for 10 minutes. |

  </div>

  <h3>Status Values</h3>

  <div class="table-wrap">

| Status                                                           | Description                                                             |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------- |
| <span class="status status-blue">UPLOADED</span>                 | File received, queued for processing                                    |
| <span class="status status-yellow">PROCESSING</span>             | Import is currently being processed                                     |
| <span class="status status-green">IMPORTED</span>                | Successfully imported without errors                                    |
| <span class="status status-orange">IMPORTED\_WITH\_ERRORS</span> | Imported with some row-level validation errors (error report available) |
| <span class="status status-red">ERROR</span>                     | Import failed due to an unrecoverable error                             |

  </div>

  <h3>Error Responses</h3>

  <div class="table-wrap">

| HTTP Status      | Description                                               | Example Message                                     |
| ---------------- | --------------------------------------------------------- | --------------------------------------------------- |
| <code>401</code> | Unauthorized                                              | Authentication credentials are missing or invalid.  |
| <code>403</code> | Forbidden                                                 | Insufficient permissions to perform this operation. |
| <code>404</code> | Not Found — no import with this ID exists for the account | No forecast import found with the specified ID.     |

  </div>

  <hr class="divider" />

  <h2 id="csv-format">CSV File Format</h2>

  <p>The CSV file must contain the following columns (<strong>exact header names, in order, case-sensitive</strong>):</p>

  <div class="table-wrap">

| Column                                  | Required                                  | Type    | Description                                                                 |
| --------------------------------------- | ----------------------------------------- | ------- | --------------------------------------------------------------------------- |
| <code>Queue</code>                      | <span class="badge badge-blue">Yes</span> | string  | Queue name — must match an active queue in WFM                              |
| <code>Datetime</code>                   | <span class="badge badge-blue">Yes</span> | string  | Date and time of the interval (format: <code>{date_format} HH:mm:ss</code>) |
| <code>Interaction volume offered</code> | <span class="badge badge-blue">Yes</span> | integer | Number of forecasted interactions                                           |
| <code>Average handle time</code>        | <span class="badge badge-blue">Yes</span> | integer | Average handle time in seconds                                              |
| <code>Shrinkage</code>                  | No                                        | number  | Shrinkage percentage (0–99)                                                 |

  </div>

  <h3>Example CSV</h3>

  <pre>Queue,Datetime,Interaction volume offered,Average handle time,Shrinkage
Sales,15/01/2025 09:00:00,120,180,15
Sales,15/01/2025 09:15:00,95,200,15
Support,15/01/2025 09:00:00,200,300,20</pre>

  <hr class="divider" />

  <h2 id="auth">Authentication &amp; Authorization</h2>

  <p>This API requires <strong>OAuth 2.0 authentication</strong> (Bearer token).</p>

  <h3>Scopes (Early Access)</h3>

  <div class="table-wrap">

| Scope                         | Required for                 |
| ----------------------------- | ---------------------------- |
| <code>wfm-public:write</code> | POST — upload forecast       |
| <code>wfm-public:read</code>  | GET — retrieve import status |

  </div>

  <hr class="divider" />

  <h2 id="limits">Subscription Limits</h2>

  <div class="panel panel-note">
    <strong>Note</strong>
    <ul style="margin:0; padding-left:20px;">
      <li>Only one forecast import can be in progress per account at any time.</li>
      <li>The error file download URL expires <strong>10 minutes</strong> after generation.</li>
    </ul>
  </div>

</body>
</html>