Download ZIP Archive

To download all files in a folder or an entire folder structure, you have to create and download a ZIP archive.

Create a ZIP Archive

First, you need to create a ZIP archive containing the files or the folder structure. You can include up to 10,000 file and folder IDs unless you reach the account’s upload limit.

curl -i -X POST "https://api.box.com/2.0/zip_downloads" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -d '{
       "download_file_name": "January Financials",
       "items": [
         {
           "type": "file",
           "id": "12345"
         },
         {
           "type": "file",
           "id": "34325"
         },
         {
           "type": "folder",
           "id": "45678"
         }
       ]
     }'

await client.zipDownloads.createZipDownload({
  items: [
    {
      id: file1.id,
      type: 'file' as ZipDownloadRequestItemsTypeField,
    } satisfies ZipDownloadRequestItemsField,
    {
      id: file2.id,
      type: 'file' as ZipDownloadRequestItemsTypeField,
    } satisfies ZipDownloadRequestItemsField,
    {
      id: folder1.id,
      type: 'folder' as ZipDownloadRequestItemsTypeField,
    } satisfies ZipDownloadRequestItemsField,
  ],
  downloadFileName: 'zip',
} satisfies ZipDownloadRequest);

client.zip_downloads.create_zip_download(
    [
        CreateZipDownloadItems(id=file_1.id, type=DownloadZipItemsTypeField.FILE),
        CreateZipDownloadItems(id=file_2.id, type=DownloadZipItemsTypeField.FILE),
        CreateZipDownloadItems(id=folder_1.id, type=DownloadZipItemsTypeField.FOLDER),
    ],
    download_file_name="zip",
)

await client.ZipDownloads.CreateZipDownloadAsync(requestBody: new ZipDownloadRequest(items: Array.AsReadOnly(new [] {new ZipDownloadRequestItemsField(id: file1.Id, type: ZipDownloadRequestItemsTypeField.File),new ZipDownloadRequestItemsField(id: file2.Id, type: ZipDownloadRequestItemsTypeField.File),new ZipDownloadRequestItemsField(id: folder1.Id, type: ZipDownloadRequestItemsTypeField.Folder)})) { DownloadFileName = "zip" });

try await client.zipDownloads.createZipDownload(requestBody: ZipDownloadRequest(items: [ZipDownloadRequestItemsField(id: file1.id, type: ZipDownloadRequestItemsTypeField.file), ZipDownloadRequestItemsField(id: file2.id, type: ZipDownloadRequestItemsTypeField.file), ZipDownloadRequestItemsField(id: folder1.id, type: ZipDownloadRequestItemsTypeField.folder)], downloadFileName: "zip"))

client.getZipDownloads().createZipDownload(new ZipDownloadRequest.Builder(Arrays.asList(new ZipDownloadRequestItemsField(ZipDownloadRequestItemsTypeField.FILE, file1.getId()), new ZipDownloadRequestItemsField(ZipDownloadRequestItemsTypeField.FILE, file2.getId()), new ZipDownloadRequestItemsField(ZipDownloadRequestItemsTypeField.FOLDER, folder1.getId()))).downloadFileName("zip").build())

ArrayList<BoxZipItem> items = new ArrayList<BoxZipItem>();
BoxZipItem file = new BoxZipItem("file", "12345");
BoxZipItem folder = new BoxZipItem("folder", "156472");
items.add(file);
items.add(folder);
BoxZip zip = new BoxZip(api);
BoxZipInfo zipInfo = zip.create("Awesome Zip File", items);

var name = 'test',
items = [
 {
  type: 'file',
  id: '466239504569'
 },
 {
  type: 'folder',
  id: '466239504580'
 }
];
client.files.createZip(name, items)
 .then(zip => {
  /* zip -> {
    "download_url": "https://api.box.com/2.0/zip_downloads/124hfiowk3fa8kmrwh/content",
    "status_url": "https://api.box.com/2.0/zip_downloads/124hfiowk3fa8kmrwh/status",
    "expires_at": "2018-04-25T11:00:18-07:00",
    "name_conflicts": [
     [
      {
       "id": "100",
       "type": "file",
       "original_name": "salary.pdf",
       "download_name": "aqc823.pdf"
      },
      {
       "id": "200",
       "type": "file",
       "original_name": "salary.pdf",
       "download_name": "aci23s.pdf"
      }
     ],
     [
      {
       "id": "1000",
       "type": "folder",
       "original_name": "employees",
       "download_name": "3d366a_employees"
      },
      {
       "id": "2000",
       "type": "folder",
       "original_name": "employees",
       "download_name": "3aa6a7_employees"
      }
     ]
    ]
   }
  */
 });

The response will look similar to the following:

{
  "download_url": "https://dl.boxcloud.com/2.0/zip_downloads/25gvaXcIE4QJlinNiw2oHAQ==ZFs3Q2Xpd7pKBz7OyzXNrUaoW3aJxQRN5znAvyM-KpdEEPdWcQDKU-Dl85Ew/content",
  "status_url": "https://api.box.com/2.0/zip_downloads/25gvaXcIE4QJlinNiw2oHAQ==ZFs3Q2Xpd7pKBz7OyzXNrUaoW3aJxQRN5znAvyM-KpdEEPdWcQDKU-Dl85Ew/status",
  "expires_at": "2023-02-28T10:23:54Z",
  "name_conflicts": []
}

File and folder names in the archive

Names inside the ZIP archive can differ from the names you see in Box. Box adjusts names so the archive extracts on Windows, and so each path fits in the archive. Box makes each file and folder name Windows-safe:

Names are normalized to Unicode NFC, so names that macOS stores in NFD form, including CJK and Japanese names, stay intact.
Characters that Windows does not allow (<, >, :, ", /, \, |, ?, and *) and control characters are replaced with _.
Windows reserved names, such as CON, PRN, NUL, ., and .., get a trailing _.
A file name cannot end with a period. A trailing period is replaced with _.

A full path in the archive is limited to 245 characters. When a path is longer than that limit:

Folder names are replaced with _, starting at the folder level that makes the path too long, until the path fits.
If the path is still too long, the file name is shortened. The extension is kept when possible.
If the path is still longer than 245 characters, the download fails.

Duplicate names in the same folder get a numeric suffix. For example, report.pdf is saved as report(1).pdf. Files from one Box folder stay in that one folder in the archive. Shortening a file name does not place those files in an extra folder. When the request includes items that share a name, name_conflicts maps each original_name to the download_name used in the archive.

Extract the ZIP download ID

To download the ZIP archive, you need the ZIP download ID. You can find it in the response you got when you created the archive. Go to status_url and copy the ID located between zip_downloads and content:

25gvaXcIE4QJlinNiw2oHAQ==ZFs3Q2Xpd7pKBz7OyzXNrUaoW3aJxQRN5znAvyM-KpdEEPdWcQDKU-Dl85Ew

Download URL is valid only for the time specified in expires_at parameter.

Download files

Place the download ID in the file location URL as in the sample below to point to the right files.

curl -L GET "https://dl.boxcloud.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/content" \
     -H "authorization: Bearer <ACCESS_TOKEN>" \
     -o sample_curl.zip

await client.zipDownloads.getZipDownloadContent(zipDownload.downloadUrl!);

client.zip_downloads.get_zip_download_content(zip_download.download_url)

await client.ZipDownloads.GetZipDownloadContentAsync(downloadUrl: NullableUtils.Unwrap(zipDownload.DownloadUrl));

try await client.zipDownloads.getZipDownloadContent(downloadUrl: zipDownload.downloadUrl!, downloadDestinationUrl: URL(path: destinationPathString))

client.getZipDownloads().getZipDownloadContent(zipDownload.getDownloadUrl())

ArrayList<BoxZipItem> items = new ArrayList<BoxZipItem>();
BoxZipItem file = new BoxZipItem("file", "12345");
BoxZipItem folder = new BoxZipItem("folder", "156472");
items.add(file);
items.add(folder);
BoxZip zip = new BoxZip(api);
FileOutputStream stream = new FileOutputStream();
BoxZipDownloadStatus zipDownloadStatus = zip.download("Another Awesome Zip File", items, stream);
stream.close();
if (zipDownloadStatus.getState() == BoxZipDownloadStatus.State.SUCCEEDED) {
    System.out.println("Zip downloaded successfully");
}

name = 'test'
file = mock_client.file('466239504569')
folder = mock_client.folder('466239504580')
items = [file, folder]
output_file = open('test.zip', 'wb')
status = client.download_zip(name, items, output_file)
print(f'The status of the zip download is {status["state"]}')

BoxZipRequest request = new BoxZipRequest();
request.Name = "test";
request.Items = new List<BoxZipItemRequest>();

var file = new BoxZipRequestItem()
{
    Id = "466239504569",
    Type = BoxZipItemType.file
};
var folder = new BoxZipRequestItem()
{
    Id = "466239504580",
    Type = BoxZipItemType.folder
};
request.Items.Add(file);
request.Items.Add(folder);
Stream fs = new FileStream(@"c:\temp\MyTest.zip");

BoxZipDownloadStatus status = await _filesManager.DownloadZip(request, fs);

var name = 'test',
items = [
 {
  type: 'file',
  id: '466239504569'
 },
 {
  type: 'folder',
  id: '466239504580'
 }
],
stream = new Readable();
client.files.downloadZip(name, items, stream)
 .then(status => {
  /* status -> {
    "total_file_count": 20,
    "downloaded_file_count": 10,
    "skipped_file_count": 10,
    "skipped_folder_count": 10,
    "state": "succeeded"
   }
  */
 });

For downloads that take longer, you can monitor the download status using the . This allows you to inspect the progress of the download as well as the number of items that might have been skipped.

curl -i -X GET "https://api.box.com/2.0/zip_downloads/29l00nfxDyHOt7RphI9zT_w==nDnZEDjY2S8iEWWCHEEiptFxwoWojjlibZjJ6geuE5xnXENDTPxzgbks_yY=/status" \
     -H "authorization: Bearer <ACCESS_TOKEN>"

await client.zipDownloads.getZipDownloadStatus(zipDownload.statusUrl!);

client.zip_downloads.get_zip_download_status(zip_download.status_url)

await client.ZipDownloads.GetZipDownloadStatusAsync(statusUrl: NullableUtils.Unwrap(zipDownload.StatusUrl));

try await client.zipDownloads.getZipDownloadStatus(statusUrl: zipDownload.statusUrl!)

client.getZipDownloads().getZipDownloadStatus(zipDownload.getStatusUrl())

If you want to use SDKs to download the contents of the folder, follow guide.

Getting started

Applications & integrations

Identity & access

Using the API

Troubleshooting

Content

Collaboration

Metadata & search

Events & webhooks

Users

Intelligent workflow

E-signatures

Security & compliance

Create a ZIP Archive

File and folder names in the archive

Extract the ZIP download ID

Download files

​Create a ZIP Archive

​File and folder names in the archive

​Extract the ZIP download ID

​Download files

Create a ZIP Archive

File and folder names in the archive

Extract the ZIP download ID

Download files