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

# WFM Schedule Import API

</style>

</head>
<body>

  <h1>WFM Schedule Event 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-event-imports">POST /wfm/aion/v1/schedules/event-imports</a></li>
          <li><a href="#get-event-imports">GET /wfm/aion/v1/schedules/event-imports/{import_id}</a></li>
        </ol>
      </li>
      <li><a href="#csv-format">CSV File Format</a></li>
      <li><a href="#date-formats">Supported Date Formats</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) Schedule Event Import API allows customers to programmatically upload agent schedule events 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 managed agent schedules (e.g., from third-party HRIS or workforce planning tools) into Talkdesk WFM.</li>
    <li>Bulk-uploading shifts, time-off, breaks, and meetings for multiple agents across date ranges.</li>
    <li>Automating periodic schedule uploads as part of an HRIS-to-WFM integration 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 schedule events via CSV:</strong> Submit a CSV file containing agent schedule events (shifts, time-off, breaks, meetings) with agent identification, time ranges, and event types.</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 schedule integration:</strong> Organizations that manage agent schedules in external HRIS or workforce planning systems can push their schedule data into Talkdesk WFM without manual data entry in the UI, enabling WFM to become the single pane of glass for adherence monitoring.</li>
    <li><strong>Bulk schedule uploads:</strong> Supervisors and planners who need to create schedules for many agents can prepare the data in a spreadsheet and upload it in a single operation rather than creating each event individually.</li>
    <li><strong>Automated planning workflows:</strong> Enterprises with mature planning processes can integrate schedule uploads into their automated workflows (e.g., nightly batch jobs that sync schedules from an HRIS system 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>Agent Name</code>, <code>Agent Email</code>, <code>Start Time</code>, <code>End Time</code>, <code>Event Type Name</code>.</li>
      <li>Agent emails in the CSV must match existing active agents configured in the Talkdesk account.</li>
      <li>Event type names must match existing event types configured in Talkdesk WFM.</li>
      <li>The maximum file size for the CSV upload is <strong>5 MB</strong>.</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 schedule data from an external HRIS system</h3>

  <p>A workforce planner exports agent schedules from a third-party HRIS system as a CSV file with the required columns and uploads it via the API:</p>

  <ul>
    <li>Upload the CSV using <code>POST /wfm/aion/v1/schedules/event-imports</code> with the schedule file, specifying the date format and timezone.</li>
    <li>The response returns <code>202 Accepted</code> with a <code>Location</code> header containing the import status URL. Use it to poll the status via <code>GET /wfm/aion/v1/schedules/event-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_report_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 Schedule Event Import API provides two endpoints:</p>

  <ul>
    <li><strong>POST /wfm/aion/v1/schedules/event-imports</strong> — Upload a schedule event CSV file</li>
    <li><strong>GET /wfm/aion/v1/schedules/event-imports/{import_id}</strong> — Retrieve the import status by ID</li>
  </ul>

  <h3 id="post-event-imports">POST /wfm/aion/v1/schedules/event-imports</h3>

  <div class="endpoint"><span class="method method-post">POST</span>https://api.talkdeskapp.com/wfm/aion/v1/schedules/event-imports</div>

  <p>Upload a schedule event CSV file for the account. Returns <code>202 Accepted</code> with a <code>Location</code> header pointing to the import status resource. No synchronous processing of CSV rows occurs before the response is sent.</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 (max 5 MB)                                                                                |
| <code>file\_name</code>   | string | <span class="badge badge-blue">Yes</span> | —                             | The original file name, must end with <code>.csv</code>                                                          |
| <code>time\_zone</code>   | string | <span class="badge badge-blue">Yes</span> | —                             | IANA time zone for the time values in the CSV (e.g., <code>America/New\_York</code>, <code>UTC</code>)           |
| <code>date\_format</code> | string | No                                        | <code>HH:mm yyyy-MM-dd</code> | Date/time format used in the Start Time and End Time columns. See <a href="#date-formats">supported formats</a>. |

  </div>

  <h3>Response: 202 Accepted</h3>

  <p>The response body is empty. The import ID is embedded in the <code>Location</code> header.</p>

  <h3>Response Headers</h3>

  <div class="table-wrap">

| Header                | Description                                                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------------ |
| <code>Location</code> | URL to check the import status, e.g. <code>/v1/schedules/event-imports/550e8400-e29b-41d4-a716-446655440000</code> |

  </div>

  <h3>Error Responses</h3>

  <div class="table-wrap">

| HTTP Status      | Error Code           | Description                                                           | Message                                                              |
| ---------------- | -------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------- |
| <code>400</code> | <code>1580028</code> | Bad Request — invalid CSV header or unsupported date format           | The CSV template is incorrect.                                       |
| <code>401</code> | <code>1580005</code> | Unauthorized — missing or invalid JWT                                 | Invalid authentication.                                              |
| <code>403</code> | —                    | Forbidden — valid JWT but missing <code>wfm-public:write</code> scope | Insufficient permissions to perform this operation.                  |
| <code>409</code> | <code>1580026</code> | Conflict — a schedule event import is already in progress             | Another event import is already in progress. Please try again later. |
| <code>413</code> | <code>1580047</code> | Payload Too Large — CSV file exceeds 5 MB                             | The uploaded file exceeds the maximum allowed size of 5 MB.          |
| <code>415</code> | <code>1580027</code> | Unsupported Media Type — only <code>.csv</code> files are accepted    | Unsupported Media Type.                                              |
| <code>429</code> | —                    | Too Many Requests                                                     | Rate limit exceeded. Please retry later.                             |

  </div>

  <h3 id="get-event-imports">GET /wfm/aion/v1/schedules/event-imports/{import_id}</h3>

  <div class="endpoint"><span class="method method-get">GET</span>https://api.talkdeskapp.com/wfm/aion/v1/schedules/event-imports/{import_id}</div>

  <p>Retrieve the current status of a Schedule Event Import by its ID. The import must belong to the authenticated account; requesting an import from a different account returns <code>404</code>.</p>

  <h3>Path Parameters</h3>

  <div class="table-wrap">

| Parameter               | Type          | Required                                  | Description                                                                                                               |
| ----------------------- | ------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| <code>import\_id</code> | string (UUID) | <span class="badge badge-blue">Yes</span> | The unique identifier of the schedule event import (extracted from the <code>Location</code> header of the POST response) |

  </div>

  <h3>Response: 200 OK</h3>

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

  <pre>{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "IMPORTED"
}</pre>

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

  <pre>{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "IMPORTED_WITH_ERRORS",
  "error_report_url": "https://s3.amazonaws.com/bucket/schedule_event_import_errors.csv?X-Amz-Expires=600",
  "error_report_expires_at": "2026-06-01T12:10:00Z"
}</pre>

  <h3>Response Fields</h3>

  <div class="table-wrap">

| Field                                   | Type                         | Required                                  | Description                                                                                                                                |
| --------------------------------------- | ---------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| <code>id</code>                         | string (UUID)                | <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>error\_report\_url</code>         | string (nullable)            | No                                        | Pre-signed S3 URL to download the error report CSV. Present only when status is <code>IMPORTED\_WITH\_ERRORS</code>. Valid for 10 minutes. |
| <code>error\_report\_expires\_at</code> | string (date-time, nullable) | No                                        | Expiry timestamp (ISO 8601) of the pre-signed URL. Present only when <code>error\_report\_url</code> is set.                               |

  </div>

  <h3>Status Values</h3>

  <div class="table-wrap">

| Status                                                           | Description                                                             |
| ---------------------------------------------------------------- | ----------------------------------------------------------------------- |
| <span class="status status-yellow">PROCESSING</span>             | File received or 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      | Error Code           | Description                                                          | Message                                             |
| ---------------- | -------------------- | -------------------------------------------------------------------- | --------------------------------------------------- |
| <code>401</code> | <code>1580005</code> | Unauthorized — missing or invalid JWT                                | Invalid authentication.                             |
| <code>403</code> | —                    | Forbidden — valid JWT but missing <code>wfm-public:read</code> scope | Insufficient permissions to perform this operation. |
| <code>404</code> | <code>1580001</code> | Not Found — no import with this ID exists for the account            | Not found.                                          |

  </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>Agent Name</code>      | <span class="badge badge-blue">Yes</span> | string | Display name of the agent                                                                                                             |
| <code>Agent Email</code>     | <span class="badge badge-blue">Yes</span> | string | Email address of the agent — must match an active agent in the Talkdesk account                                                       |
| <code>Start Time</code>      | <span class="badge badge-blue">Yes</span> | string | Start date and time of the schedule event (format must match the <code>date\_format</code> parameter)                                 |
| <code>End Time</code>        | <span class="badge badge-blue">Yes</span> | string | End date and time of the schedule event (format must match the <code>date\_format</code> parameter)                                   |
| <code>Event Type Name</code> | <span class="badge badge-blue">Yes</span> | string | Name of the event type — must match an existing event type configured in Talkdesk WFM (e.g., <code>Available for all channels</code>) |

  </div>

  <h3>Example CSV (default <code>HH:mm yyyy-MM-dd</code> format)</h3>

  <pre>Agent Name,Agent Email,Start Time,End Time,Event Type Name
John Smith,john.smith@example.com,09:00 2026-06-01,17:00 2026-06-01,Available for all channels
Jane Doe,jane.doe@example.com,08:00 2026-06-01,16:00 2026-06-01,Available for all channels
Bob Wilson,bob.wilson@example.com,12:00 2026-06-01,12:30 2026-06-01,Break</pre>

  <h3>Example CSV (<code>HH:mm MM/dd/yyyy</code> format)</h3>

  <pre>Agent Name,Agent Email,Start Time,End Time,Event Type Name
John Smith,john.smith@example.com,09:00 06/01/2026,17:00 06/01/2026,Available for all channels
Jane Doe,jane.doe@example.com,08:00 06/01/2026,16:00 06/01/2026,Available for all channels</pre>

  <hr class="divider" />

  <h2 id="date-formats">Supported Date Formats</h2>

  <p>The <code>date_format</code> parameter accepts the following values:</p>

  <div class="table-wrap">

| Format String                 | Example Value                 | Description                                                 |
| ----------------------------- | ----------------------------- | ----------------------------------------------------------- |
| <code>HH:mm yyyy-MM-dd</code> | <code>09:00 2026-06-01</code> | Default. 24-hour time followed by ISO date.                 |
| <code>HH:mm yyyyMMdd</code>   | <code>09:00 20260601</code>   | 24-hour time followed by compact date.                      |
| <code>HH:mm MM/dd/yyyy</code> | <code>09:00 06/01/2026</code> | 24-hour time followed by US date format.                    |
| <code>HH:mm M/d/yyyy</code>   | <code>09:00 6/1/2026</code>   | 24-hour time followed by US date format (no leading zeros). |
| <code>HH:mm MM/dd/yy</code>   | <code>09:00 06/01/26</code>   | 24-hour time followed by US date format with 2-digit year.  |
| <code>HH:mm dd/MM/yyyy</code> | <code>09:00 01/06/2026</code> | 24-hour time followed by European date format.              |

  </div>

  <hr class="divider" />

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

  <p>This API requires <strong>OAuth 2.0 authentication</strong> (Bearer token) using the client credentials grant.</p>

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

  <div class="table-wrap">

| Scope                         | Required for                  |
| ----------------------------- | ----------------------------- |
| <code>wfm-public:write</code> | POST — upload schedule events |
| <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 schedule event import can be in progress per account at any time.</li>
      <li>The maximum CSV file size is <strong>5 MB</strong>.</li>
      <li>The error report download URL expires <strong>10 minutes</strong> after generation.</li>
    </ul>
  </div>

</body>
</html>