WFM Forecast Import API — Public Documentation

WFM Forecast Import API

On this page

Overview
Business Problem-Solving Context
Use Case
Usage
1. POST /forecast_imports
2. GET /forecast_imports/{import_id}
CSV File Format
Authentication & Authorization
Subscription Limits

Overview

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 Talkdesk Workforce Management product.

Typical use cases include:

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

Business Problem-Solving Context

What can I achieve with this API?

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

What business problems does this API solve?

Third-party forecast integration: Organizations that use external forecasting tools or statistical models can push their forecast data into Talkdesk WFM without manual data entry in the UI.
Bulk forecast overrides: 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.
Automated planning workflows: 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).

What does this API support and what are its limitations?

Limitations

Only one import per account can be in progress at any time. Attempting a second concurrent upload returns a 409 Conflict error.
The CSV file must use specific column headers: Queue, Datetime, Interaction volume offered, Average handle time, and optionally Shrinkage.
Queue names in the CSV must match existing active queues configured in Talkdesk WFM.
Datetime values must align with the specified interval_editing granularity (15 minutes, 30 minutes, or 1 hour).
The error file download URL (for imports with partial errors) is valid for 10 minutes after generation.

Use Case

Importing forecast data from an external planning tool

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:

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

Usage

The Forecast Import API provides two endpoints:

POST /forecast_imports — Upload a forecast CSV file
GET /forecast_imports/{import_id} — Retrieve the import status by ID

POST /forecast_imports

POST/forecast_imports

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 Content-Location header.

Content-Type: multipart/form-data

Request Parameters (form data)

Parameter	Type	Required	Default	Description
`csv_file`	binary	Yes	—	The CSV file to upload
`file_name`	string	Yes	—	The original file name including the `.csv` extension (max 255 characters)
`time_zone`	string	Yes	—	IANA time zone of the datetime values in the CSV (e.g., `America/New_York`, max 64 characters)
`date_format`	string	No	`DD/MM/YYYY`	Date format used in the Datetime column (e.g., `MM/DD/YYYY`, max 32 characters)
`interval_editing`	string	No	`MIN_15`	Interval granularity for forecast editing. Values: `MIN_15`, `MIN_30`, `HOUR`
`trigger_scheduler_job`	boolean	No	`false`	Whether to trigger the scheduler job after the import completes

Response: 202 Accepted

{
  "id": "8ae6a6b17c6fcc00017c6fddd2c00001",
  "status": "UPLOADED"
}

Response Headers

Header	Description
`Content-Location`	URL to check the import status

Error Responses

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

GET /forecast_imports/{import_id}

GET/forecast_imports/{import_id}

Retrieve the current status of a Forecast Import by its ID.

Path Parameters

Parameter	Type	Required	Description
`import_id`	string	Yes	The unique identifier of the forecast import

Response: 200 OK

Success example:

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

With errors example:

{
  "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"
}

Response Fields

Field	Type	Required	Description
`id`	string	Yes	The unique identifier of the import
`status`	string	Yes	The current processing status
`created_at`	string (date-time)	Yes	When the import was created
`updated_at`	string (date-time)	Yes	When the import was last updated
`error_file_url`	string (nullable)	No	Pre-signed URL to download the error report CSV. Present only when status is `IMPORTED_WITH_ERRORS` or `ERROR`. Valid for 10 minutes.

Status Values

Status	Description
UPLOADED	File received, queued for processing
PROCESSING	Import is currently being processed
IMPORTED	Successfully imported without errors
IMPORTED_WITH_ERRORS	Imported with some row-level validation errors (error report available)
ERROR	Import failed due to an unrecoverable error

Error Responses

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

CSV File Format

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

Column	Required	Type	Description
`Queue`	Yes	string	Queue name — must match an active queue in WFM
`Datetime`	Yes	string	Date and time of the interval (format: `{date_format} HH:mm:ss`)
`Interaction volume offered`	Yes	integer	Number of forecasted interactions
`Average handle time`	Yes	integer	Average handle time in seconds
`Shrinkage`	No	number	Shrinkage percentage (0–99)

Example CSV

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

Authentication & Authorization

This API requires OAuth 2.0 authentication (Bearer token).

Scopes (Early Access)

Scope	Required for
`wfm-public:write`	POST — upload forecast
`wfm-public:read`	GET — retrieve import status

Subscription Limits

Note

Only one forecast import can be in progress per account at any time.
The error file download URL expires 10 minutes after generation.