Introduction to Files Management APIs#

Workiva’s Files Management APIs allow users to manage files and folders within the Workiva Platform. File management options include creating, importing, exporting, copying, and organizing files into folders.

This guide goes over the following scenarios:

How do I import a non-Workiva file as a Workiva file type?
How do I upload a non-Workiva file such as a PDF into the Workiva Platform?
How do I export a Workiva Spreadsheet and import it into a different workspace?
How do I target a specific folder when importing a file?
How do I copy a file into a specific folder?

How do I import a non-Workiva file as a Workiva file type?#

The import file endpoint converts common file formats into their Workiva equivalents. Supported conversions include:

Source Format	Target Kind
`.XLSX`	`Spreadsheet`
`.CSV`	`Spreadsheet`
`.DOCX`	`Document`
`.PPTX`	`Presentation`
`.VSDX`	`Presentation`

Importing a file is a 4 step process, initiating the import to receive a signed upload URL, uploading the file to that URL, then polling for completion to retrieve the newly created file’s ID.

Step 1: Initiate the import#

Make a POST import file request with the fileName and target kind.

Request#

curl -X POST https://api.app.wdesk.com/files/import \
    -H "Authorization: Bearer ${token}" \
    -H "X-Version: 2026-01-01" \
    --data @body.json

Request Body#

{
    "fileName": "Q4_Financials.xlsx",
    "kind": "Spreadsheet"
}

The response returns an uploadUrl for uploading the file and an operationLocation for polling the operation status. The Location and Retry-After headers are also included.

Response#

{
    "operationLocation": "https://api.app.wdesk.com/operations/<operationId>",
    "uploadUrl": "<opaque_url>"
}

Response Headers#

Location: https://api.app.wdesk.com/operations/<operationId>
Retry-After: 5

Step 2: Upload the file#

Perform a PUT request to the uploadUrl from the response. The request body is the raw file content. Use the same authentication credentials and flow as the import request.

Request#

curl -X PUT "<uploadUrl>" \
    -H "Authorization: Bearer ${token}" \
    -H "Content-Type: application/octet-stream" \
    --data-binary @Q4_Financials.xlsx

Step 3: Poll for completion#

The import is a long-running operation. Poll the Location URL from the response headers until the operation status is completed. Respect the Retry-After header between polling attempts.

Request#

curl -X GET https://api.app.wdesk.com/operations/<operationId> \
    -H "Authorization: Bearer ${token}" \
    -H "X-Version: 2026-01-01"

Response#

{
    "id": "<operationId>",
    "status": "started",
    "created": {
        "dateTime": "2026-01-15T10:00:00Z"
    },
    "updated": {
        "dateTime": "2026-01-15T10:00:05Z"
    },
    "originalRequest": "<requestId>"
}

Once the operation reaches completed status, its resourceUrl points to the import file results endpoint. Query this URL to retrieve the ID and kind of the newly created file.

Response#

{
    "id": "<operationId>",
    "status": "completed",
    "resourceUrl": "https://api.app.wdesk.com/operations/<operationId>/importFileResults",
    "created": {
        "dateTime": "2026-01-15T10:00:00Z"
    },
    "updated": {
        "dateTime": "2026-01-15T10:00:30Z"
    },
    "originalRequest": "<requestId>"
}

Step 4: Retrieve the import results#

Request#

curl -X GET https://api.app.wdesk.com/operations/<operationId>/importFileResults \
    -H "Authorization: Bearer ${token}" \
    -H "X-Version: 2026-01-01"

Response#

{
    "data": [
        {
            "id": "124efa2a142f472ba1ceab34ed18915f",
            "container": "",
            "kind": "Spreadsheet"
        }
    ]
}

The id field is the unique identifier of the newly created Workiva file. You can use this ID with other endpoints such as GET file by ID or the Spreadsheets and Documents endpoints to interact with the imported content.

Note

This endpoint is rate-limited. You may experience rates as low as 1 request per second. When polling for updates, examine the Retry-After header and retry after that many seconds.

For more information about async operations, see Introduction to Operations.

How do I upload a non-Workiva file such as a PDF into the Workiva Platform?#

Files that do not have a Workiva equivalent—such as PDFs, images, or other arbitrary file types—can be uploaded as Supporting Documents. Unlike standard imports which convert the file into a Workiva type, a Supporting Document preserves the original file as-is within the platform.

Use the same POST import file endpoint with kind set to SupportingDocument. Supporting Document imports accept any file extension.

Step 1: Initiate the import#

Request#

curl -X POST https://api.app.wdesk.com/files/import \
    -H "Authorization: Bearer ${token}" \
    -H "X-Version: 2026-01-01" \
    --data @body.json

Request Body#

{
    "fileName": "signed_contract.pdf",
    "kind": "SupportingDocument"
}

Optionally, you can place the Supporting Document into a specific folder by providing supportingDocumentImportOptions with a containerId:

Request Body#

{
    "fileName": "signed_contract.pdf",
    "kind": "SupportingDocument",
    "supportingDocumentImportOptions": {
        "containerId": "V0ZEYXRhRW5zVkNmU2Zi1mZjcE4EzNzk0ZmUwZjk"
    }
}

Set containerId to an empty string ("") to import to the root folder.

Step 2: Upload the file#

Upload the file to the returned uploadUrl using a PUT request, just as with any other import.

Request#

curl -X PUT "<uploadUrl>" \
    -H "Authorization: Bearer ${token}" \
    -H "Content-Type: application/octet-stream" \
    --data-binary @signed_contract.pdf

Step 3: Poll and retrieve results#

Follow the same polling pattern described above. Poll the operation until it reaches completed status, then retrieve the results from the resourceUrl.

Tip

Supporting Documents are listed in the files list alongside other Workiva files. Their kind will be SupportingDocument and they can be managed (renamed, moved, trashed) using the same Files endpoints as any other file.

How do I export a Workiva Spreadsheet and import it into a different workspace?#

A common workflow is to transfer a Workiva Spreadsheet from one workspace to another. This requires exporting the file in the Workiva native format (.tar.gz), then importing it into the target workspace. The Workiva native format preserves Workiva-specific features such as links, formatting, XBRL tagging, and comments.

Step 1: Export the Spreadsheet as a Workiva file#

Use the POST export file by ID endpoint with kind set to Workiva and configure the desired export options.

Request#

curl -X POST https://api.app.wdesk.com/files/<fileId>/export \
    -H "Authorization: Bearer ${token}" \
    -H "X-Version: 2026-01-01" \
    --data @body.json

Request Body#

{
    "kind": "Workiva",
    "workivaFileExport": {
        "workivaFileExportOptions": {
            "emailOnComplete": false,
            "includeAttachments": true,
            "includeComments": true,
            "includeInputCellValues": true,
            "includeXBRL": true,
            "keepInputModeEnabled": true
        }
    }
}

The response returns a 202 Accepted with an operationLocation in the body and Location and Retry-After headers for tracking the long-running operation.

Response#

{
    "operationLocation": "https://api.app.wdesk.com/operations/<operationId>"
}

Response Headers#

Location: https://api.app.wdesk.com/operations/<operationId>
Retry-After: 5

The export options control which features are preserved in the exported file:

Option	Description
`includeAttachments`	Preserve attachments for exported content.
`includeComments`	Preserve comments for exported content.
`includeInputCellValues`	Preserve input cell values for exported content.
`includeXBRL`	Preserve XBRL tagging for exported content.
`includeXBRLDisconnected`	Preserve disconnected XBRL for exported content.
`includeDocumentMarkup`	Preserve document markup for exported content.
`includeOutlineLabels`	Preserve outline labels for exported content.
`includeSmartLinkMetadata`	Include smart link metadata for exported content.
`includeCustomFieldValues`	Preserve custom field values for exported content.
`includeWdataIncomingConnections`	Preserve incoming Wdata connections.
`includeWdataOutgoingConnections`	Preserve outgoing Wdata connections.
`keepInputModeEnabled`	Preserve input mode for exported content.
`removeGRCLinks`	Remove connections to the original GRC database, keeping only text/values.
`removeLinks`	Remove links from sources not part of the operation, keeping only text/values.
`emailOnComplete`	Email the authorized user when the export is complete.

Step 2: Poll for the export to complete#

Poll the operation Location URL until the status is completed. Once complete, the resourceUrl in the operation response contains the download URL for the exported .tar.gz file.

Request#

curl -X GET https://api.app.wdesk.com/operations/<operationId> \
    -H "Authorization: Bearer ${token}" \
    -H "X-Version: 2026-01-01"

Response#

{
    "id": "<operationId>",
    "status": "completed",
    "resourceUrl": "<downloadUrl>",
    "created": {
        "dateTime": "2026-01-15T10:00:00Z"
    },
    "updated": {
        "dateTime": "2026-01-15T10:02:00Z"
    },
    "originalRequest": "<requestId>"
}

Step 3: Download the exported file#

Perform a GET request against the resourceUrl to download the .tar.gz file. Use the same authentication credentials and flow as the export request.

Request#

curl -X GET "<downloadUrl>" \
    -H "Authorization: Bearer ${token}" \
    -o spreadsheet_export.tar.gz

Step 4: Import the Workiva file into the target workspace#

Authenticate against the target workspace and use the POST import file endpoint with kind set to Workiva. Provide workivaFileImportOptions to control where the file is placed and which features are preserved.

Request#

curl -X POST https://api.app.wdesk.com/files/import \
    -H "Authorization: Bearer ${token}" \
    -H "X-Version: 2026-01-01" \
    --data @body.json

Request Body#

{
    "fileName": "spreadsheet_export.tar.gz",
    "kind": "Workiva",
    "workivaFileImportOptions": {
        "destinationContainer": "V0ZEYXRhRW5zVkNmU2Zi1mZjcE4EzNzk0ZmUwZjk",
        "createNewResultContainer": true,
        "newResultContainerName": "Q4 Earnings 2026",
        "emailOnComplete": true,
        "includeAttachments": true,
        "includeComments": true,
        "includeInputCellValues": true,
        "includeXBRL": true,
        "keepInputModeEnabled": true
    }
}

Important

The destinationContainer specifies the folder in which to place the imported files. Set this to an empty string ("") to import to the root folder. When createNewResultContainer is true, the import creates a new subfolder named by newResultContainerName inside the destination container to house the imported files.

After initiating the import, upload the .tar.gz file to the returned uploadUrl, then poll the operation until complete.

Request#

curl -X PUT "<uploadUrl>" \
    -H "Authorization: Bearer ${token}" \
    -H "Content-Type: application/octet-stream" \
    --data-binary @spreadsheet_export.tar.gz

Tip

When transferring files between workspaces, make sure the export and import options are aligned. For example, if you export with includeXBRL: true, include the same option on import to preserve XBRL tagging in the destination workspace.

How do I copy a file into a specific folder?#

Use the POST copy file by ID endpoint to duplicate an existing Workiva file. You can place the copy into a target folder by providing a destinationContainer and optionally name it using options.destinationName.

Important

File Copies are only supported within a single Workspace. If you are trying to copy a file that exists in one workspace into a different workspace you will need to use the export and import API functionality to achieve this instead.

Step 1: Initiate the copy#

Make a POST request to /files/{fileId}/copy with the target destinationContainer and optional options to name the copy and control which features are preserved.

Request#

curl -X POST https://api.app.wdesk.com/files/<fileId>/copy \
    -H "Authorization: Bearer ${token}" \
    -H "X-Version: 2026-01-01" \
    --data @body.json

Request Body#

{
    "destinationContainer": "V0ZEYXRhRW5zVkNmU2Zi1mZjcE4EzNzk0ZmUwZjk",
    "options": {
        "destinationName": "Q4_Financials_Copy"
    }
}

Omit destinationContainer to place the copy in the root folder. Providing an empty string ("") is invalid for the copy endpoint.

Note

This behavior differs from Supporting Document and Workiva native imports, where an empty string ("") targets the root folder. For the copy endpoint, omit the field entirely instead.

The options object also supports preservation flags for controlling which features carry over to the copy. For a full list of options, see the POST copy file by ID endpoint reference. Here is an example with common options:

Request Body#

{
    "destinationContainer": "V0ZEYXRhRW5zVkNmU2Zi1mZjcE4EzNzk0ZmUwZjk",
    "options": {
        "destinationName": "Q4_Financials_Copy",
        "includeAttachments": true,
        "includeComments": true,
        "includeXBRL": true,
        "keepInputModeEnabled": true
    }
}

If options is omitted, all preservation flags default to false and the copy retains the original file’s name.

The response returns a 202 Accepted with an operationLocation in the body and Location and Retry-After headers for tracking the long-running operation.

Response#

{
    "operationLocation": "https://api.app.wdesk.com/operations/<operationId>"
}

Response Headers#

Location: https://api.app.wdesk.com/operations/<operationId>
Retry-After: 5

Step 2: Poll for completion#

Poll the Location URL until the operation status is completed.

Request#

curl -X GET https://api.app.wdesk.com/operations/<operationId> \
    -H "Authorization: Bearer ${token}" \
    -H "X-Version: 2026-01-01"

Response#

{
    "id": "<operationId>",
    "status": "completed",
    "resourceUrl": "https://api.app.wdesk.com/operations/<operationId>/copyFileResults",
    "created": {
        "dateTime": "2026-01-15T10:00:00Z"
    },
    "updated": {
        "dateTime": "2026-01-15T10:00:15Z"
    },
    "originalRequest": "<requestId>"
}

Step 3: Retrieve the copy results#

Query the resourceUrl to get the ID of the newly created file.

Request#

curl -X GET https://api.app.wdesk.com/operations/<operationId>/copyFileResults \
    -H "Authorization: Bearer ${token}" \
    -H "X-Version: 2026-01-01"

Response#

{
    "data": [
        {
            "id": "8f3a1c7d294e4b0fa3c6e2d1b8490f12",
            "container": "V0ZEYXRhRW5zVkNmU2Zi1mZjcE4EzNzk0ZmUwZjk",
            "kind": "Spreadsheet"
        }
    ]
}

The id field is the unique identifier of the copied file. Use this ID with other endpoints to interact with the copy.

Tip

Only Workiva file types (Document, Spreadsheet, Presentation) can be copied using this endpoint. Supporting Documents cannot be copied; to duplicate a Supporting Document, re-import the original file.

How do I target a specific folder when importing a file?#

Files in Workiva are organized into folders (also called containers). When importing a file, you can specify which folder receives the imported file. The method depends on the kind of import.

For Supporting Documents#

Use supportingDocumentImportOptions.containerId in the import request body:

Request Body#

{
    "fileName": "annual_report.pdf",
    "kind": "SupportingDocument",
    "supportingDocumentImportOptions": {
        "containerId": "V0ZEYXRhRW5zVkNmU2Zi1mZjcE4EzNzk0ZmUwZjk"
    }
}

For Workiva native imports (.tar.gz)#

Use workivaFileImportOptions.destinationContainer in the import request body:

Request Body#

{
    "fileName": "export_bundle.tar.gz",
    "kind": "Workiva",
    "workivaFileImportOptions": {
        "destinationContainer": "V0ZEYXRhRW5zVkNmU2Zi1mZjcE4EzNzk0ZmUwZjk"
    }
}

For standard file conversions (Document, Spreadsheet, Presentation)#

Standard file conversions (.XLSX, .DOCX, .PPTX, .CSV, .VSDX) do not accept a container option on the import request itself. The file is imported into the root folder by default. To place it in a specific folder after import, use the PATCH file endpoint to update the file’s container property.

First, retrieve the imported file’s ID from the import results. Then move it:

Request#

curl -X PATCH https://api.app.wdesk.com/files/<fileId> \
    -H "Authorization: Bearer ${token}" \
    -H "X-Version: 2026-01-01" \
    -H "Content-Type: application/json" \
    --data @body.json

Request Body#

[
    {
        "op": "replace",
        "path": "/container",
        "value": "V0ZEYXRhRW5zVkNmU2Zi1mZjcE4EzNzk0ZmUwZjk"
    }
]

Set value to an empty string ("") to move the file to the root folder.

Tip

To find the ID of a folder, use the GET files endpoint with a filter for kind eq 'Folder'. Folder IDs can also be found in the container property of any file that resides inside that folder.

How do I find or create a target folder?#

You can list existing folders using the GET files endpoint:

Request#

curl -X GET "https://api.app.wdesk.com/files?$filter=kind eq 'Folder'" \
    -H "Authorization: Bearer ${token}" \
    -H "X-Version: 2026-01-01"

To create a new folder, use the POST file endpoint with kind set to Folder:

Request Body#

{
    "name": "Q4 2026 Reports",
    "kind": "Folder"
}

To create a folder inside another folder, include the parent folder’s ID as the container:

Request Body#

{
    "name": "Supporting Documents",
    "kind": "Folder",
    "container": "V0ZEYXRhRW5zVkNmU2Zi1mZjcE4EzNzk0ZmUwZjk"
}

Common Concepts#

File Kinds#

Every file in Workiva has a kind that identifies its type:

Kind	Description
`Document`	A Workiva document, similar to a word processor file.
`Spreadsheet`	A Workiva spreadsheet, similar to a spreadsheet application file.
`Presentation`	A Workiva presentation, similar to a slide deck file.
`Folder`	A container for organizing other files.
`Script`	A Workiva script file.
`SupportingDocument`	A non-Workiva file (PDF, image, etc.) stored in the platform as-is.

Containers#

A container is the folder that houses a file. The container property on a File holds the unique identifier of the parent folder. If container is empty, the file resides in the root folder.

Long-Running Operations#

File imports, exports, and copies are long-running operations. These endpoints return a 202 Accepted response with an operationLocation field in the body and Location and Retry-After headers. Either the operationLocation body field or the Location header can be used to poll for status updates. When the operation reaches completed status, its resourceUrl contains the result.

Status	Meaning
`acknowledged`	The operation has been received.
`queued`	The operation is waiting to start.
`started`	The operation is in progress.
`completed`	The operation finished successfully.
`failed`	The operation failed. Check `details` for more information.

For more information, see Introduction to Operations.

Exporting to Non-Workiva Formats#

In addition to exporting as a Workiva native .tar.gz file, Workiva files can be exported to standard formats. The available formats depend on the file kind:

File Kind	Export Formats
Document	`.PDF`, `.DOCX`, `.XHTML`
Spreadsheet	`.PDF`, `.XLSX`, `.CSV`
Presentation	`.PDF`, `.PPTX`

To export a Spreadsheet as .XLSX, for example:

Request Body#

{
    "kind": "Spreadsheet",
    "spreadsheetExport": {
        "format": "xlsx",
        "xlsxOptions": {
            "exportAsFormulas": true,
            "exportPrecision": "displayed"
        }
    }
}

To export only specific sheets within a spreadsheet, include the sheets array with the IDs of the sheets to export:

Request Body#

{
    "kind": "Spreadsheet",
    "spreadsheetExport": {
        "format": "xlsx",
        "sheets": [
            "7c8d8c4a46784455bg68t36f9d8232d8",
            "54bgd83b471e5902f1a8e8c9a299c9fb"
        ]
    }
}

For more on format-specific export options, see Documents, Spreadsheets, and Presentations.

Required Scopes#

Files endpoints require the following OAuth scopes:

Operation	Required Scope
List, retrieve files	`file:read`
Create, import, export, copy, update, trash, restore files	`file:write`

Versions

Introduction to Files Management APIs

Table Of Contents

Introduction to Files Management APIs#

How do I import a non-Workiva file as a Workiva file type?#

Step 1: Initiate the import#

Step 2: Upload the file#

Step 3: Poll for completion#

Step 4: Retrieve the import results#

How do I upload a non-Workiva file such as a PDF into the Workiva Platform?#

Step 1: Initiate the import#

Step 2: Upload the file#

Step 3: Poll and retrieve results#

How do I export a Workiva Spreadsheet and import it into a different workspace?#

Step 1: Export the Spreadsheet as a Workiva file#

Step 2: Poll for the export to complete#

Step 3: Download the exported file#

Step 4: Import the Workiva file into the target workspace#

How do I copy a file into a specific folder?#

Step 1: Initiate the copy#

Step 2: Poll for completion#

Step 3: Retrieve the copy results#

How do I target a specific folder when importing a file?#

For Supporting Documents#

For Workiva native imports (.tar.gz)#

For standard file conversions (Document, Spreadsheet, Presentation)#

How do I find or create a target folder?#

Common Concepts#

File Kinds#

Containers#

Long-Running Operations#

Exporting to Non-Workiva Formats#

Required Scopes#