Working with files

Several components of the Nutshell API support uploading and downloading files. This document outlines the general workflow.

Where files are available

• Logged activities may have one or more attachments, representing the audio or video log.
• Leads can have one or more attached files
• On-demand ZIP backups can be generated and downloaded

We plan to add additional support for file attachments in the near future.

Retrieving attached files

Logged activities contain a logNote property, an object which may have one or more file objects in its files array. Multiple encodings are created after a file has been uploaded and processed.

Leads have a file property, which contains an array of files associated with this lead, typically uploaded via the web interface.

Sample file object

{
  "entityType": "Files",
  "id": 1234,
  // Where to download this file via HTTPS
  "uri": "https://app01.nutshell.com/file/api/1234", 
  "name": "activity0_log_file_1322783452",
  // An accurate MIME representation of this file
  "mime": "video\/quicktime",
  "rev": "ff6ae801b9584bb37b48d1c6273427a5942385f5",
  // Size of this file in bytes
  "size": 840464,
  // A mime-like internal representation, primarily for our mobile apps
  "clientType": "video\/iphone", 
  // Duration in ms
  "duration": 8327
}

Downloading actual file data

After retrieving the file object documented above, use the object's uri key as the endpoint for the file. You will need to use the same HTTP basic authentication that you use to access the file. Note that these endpoints support HTTP Range: requests, useful when accessing media for HTTP streaming.

Uploading files

Uploading files to Nutshell is a two-part process. First, you will edit the entity, providing the metadata for the file you are about to upload. The response from Nutshell will include a URI resource, to which you should POST the file. The process outlined below is the same for any Nutshell request that allows for uploads. (Currently editLead() and editActivity())

1. Edit a lead to indicate a new file for upload

<?php
$result = $nutshellApi->editLead(1234, 'rev', array(
  'file' => array(
    array('entityType' => 'Files', 'name' => 'my_file_to_upload.txt')
  )
));

2. Examine the response to editLead() for the URL to which you should POST

{
  "entityType": "Leads",
  "id": 1234,
  "file": [
    {
      "entityType": "Files",
      "id": 5678,
      // this is the URL to post your file
      "uri": "https://app01.nutshell.com/file/api/5678", 
      "name": "my_file_to_upload.txt",
      "mime": "",
      "rev": "",
      "size": 0,
    }
  ]
}

3. Post your file to the provided URL

After examining the response for the correct URI to upload your new file, you should create a simple HTTP POST with the contents of your file. This should just be a simple multipart/form-data POST, with file as the key for your file's data. As with downloading a file, you should use your standard HTTP Basic authentication.

You should be able to immediately download the file from the same URL resource, with an HTTP 200 status, as a way of confirming a successful upload.

Subsequent requests to retrieve the lead will now include the MIME type and size for your newly-uploaded file.