# Upload files

## Facets

Use an existing facet when you want to copy a file property. Note when creating file properties using existing facets, the source data is always copied. The following are all examples of valid content facet reference property values:

* "/accounts/5a4feb0bc4a54066c8f4c1c4/image/content"
* "accounts/5a4feb0bc4a54066c8f4c1c4/image/content"
* "facet:///accounts/5a4feb0bc4a54066c8f4c1c4/image/content"
* "facet://accounts/5a4feb0bc4a54066c8f4c1c4/image/content"
* {source: "facet", filename: "thing.png", path: "/accounts/5a4feb0bc4a54066c8f4c1c4/image/content"}

## Uploads

The following are all examples of valid content upload property values:

* "file://image.png"
* "upload://image.png"
* "image.png"
* {upload: "image.png"}
* {source: "upload", filename: "image.png"}

Uploading files is a two-stage process. Firstly, the [File](https://docs.medable.com/reference-link/files) property is written. A good example is the Account `image`, which consists of a `content` facet that expects an image. The value of the property must be an object whose properties are the configured, uploaded facet names, with their being filenames with extensions matching the content-type accepted by the facet. For example,\
updating an Account image:Example

```
// PUT accounts/5516ee2634d8d93428169c0e/image 

Request: 
    {
        "content": "IMG_1399.JPG"        
    }
Response:
{
    "creator": "5516ee2634d8d93428169c0e",
    "facets": [{
        "creator": "5516ee2634d8d93428169c0e",
        "location": 4,
        "name": "thumbnail",
        "path": "/accounts/5516ee2634d8d93428169c0e/image/thumbnail",
        "state": 0
    }],
    "location": 4,
    "name": "content",
    "path": "/accounts/5516ee2634d8d93428169c0e/image/content",
    "state": 0,
    "uploads": [{
        "fields": [{
            "key": "x-amz-credential",
            "value": "AKIAJ3Z4AWM5JO6AILYQ/20150404/us-east-1/s3/aws4_request"
        }, {
            "key": "x-amz-date",
            "value": "20150404T041333Z"
        }, {
            "key": "x-amz-server-side-encryption",
            "value": "AES256"
        }, {
            "key": "x-amz-signature",
            "value": "e78ce424cafb6ce2accbaaf49e8a2a6cc7794c79b0f7c902e1e380caf9edfefc"
        }, {
            "key": "x-amz-algorithm",
            "value": "AWS4-HMAC-SHA256"
        }, {
            "key": "success_action_status",
            "value": "201"
        }, {
            "key": "content-type",
            "value": "image/jpeg"
        }, {
            "key": "key",
            "value": "5516ee1b34d8d934281699e3/436f6e746578742041636374/5516ee2634d8d93428169c0e.image/551f64ed3f2ab234373c8465.jpeg"
        }, {
            "key": "policy",
            "value": "eyJleHBpcmF0aW9uIjoiMjAxNS0wNC0xNFQxNDoxMzozMy40MzFaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoibWVkYWJsZS11cGxvYWRzLXNjYXJsZXQifSx7ImtleSI6IjU1MTZlZTFiMzRkOGQ5MzQyODE2OTllMy80MzZmNmU3NDY1Nzg3NDIwNDE2MzYzNzQvNTUxNmVlMjYzNGQ4ZDkzNDI4MTY5YzBlLmltYWdlLzU1MWY2NGVkM2YyYWIyMzQzNzNjODQ2NS5qcGVnIn0sWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMCw1MTIwMDAwXSx7ImNvbnRlbnQtdHlwZSI6ImltYWdlL2pwZWcifSx7IngtYW16LWFsZ29yaXRobSI6IkFXUzQtSE1BQy1TSEEyNTYifSx7IngtYW16LWNyZWRlbnRpYWwiOiJBS0lBSjNaNEFXTTVKTzZBSUxZUS8yMDE1MDQwNC91cy1lYXN0LTEvczMvYXdzNF9yZXF1ZXN0In0seyJ4LWFtei1kYXRlIjoiMjAxNTA0MDRUMDQxMzMzWiJ9LHsieC1hbXotc2VydmVyLXNpZGUtZW5jcnlwdGlvbiI6IkFFUzI1NiJ9LHsic3VjY2Vzc19hY3Rpb25fc3RhdHVzIjoiMjAxIn1dfQ=="
        }],            
        "location": 5,
        "maxFileSize": 5120000,
        "name": "content",
        "state": 0,
        "uploadKey": "file",
        "uploadMethod": "post",
        "uploadUrl": "https://medable-v2-uploads.s3.amazonaws.com"
    }]
}
```

The response contains new facets with a state of 0 (Pending).

For uploads, the next step is to scan the `uploads` array in the response and make an HTTP multipart/form-data POST for each entry in the array. For each entry:

1. Build a form containing the fields defined in using the `fields` array **in the order they appear**.
2. The last field in the form must be the file field corresponding to the file to be uploaded, and the field name must be equal to the `uploadKey`.
3. The form `action` must be equal to the `uploadUrl`.
4. The form `method` must be equal to the `uploadMethod`.

An html form for the above example might look like this:HTML

```
<form action="https://medable-v2-uploads.s3.amazonaws.com" method="post" enctype="multipart/form-data">
    <input type="hidden" name="x-amz-credential" value="AKIAJ3Z4AWM5JO6AILYQ/20150404/us-east-1/s3/aws4_request">
    <input type="hidden" name="x-amz-date" value="20150404T041333Z">
    <input type="hidden" name="x-amz-server-side-encryption" value="AES256">
    <input type="hidden" name="x-amz-signature" value="e78ce424cafb6ce2accbaaf49e8a2a6cc7794c79b0f7c902e1e380caf9edfefc">
    <input type="hidden" name="x-amz-algorithm" value="AWS4-HMAC-SHA256">
    <input type="hidden" name="success_action_status" value="201">
    <input type="hidden" name="key" value="5516ee1b34d8d934281699e3/436f6e746578742041636374/5516ee2634d8d93428169c0e.image/551f64ed3f2ab234373c8465.jpeg">
    <input type="hidden" name="policy" value="eyJleHBpcmF0aW9uIjoiMjAxNS0wNC0xNFQxNDoxMzozMy40MzFaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoibWVkYWJsZS11cGxvYWRzLXNjYXJsZXQifSx7ImtleSI6IjU1MTZlZTFiMzRkOGQ5MzQyODE2OTllMy80MzZmNmU3NDY1Nzg3NDIwNDE2MzYzNzQvNTUxNmVlMjYzNGQ4ZDkzNDI4MTY5YzBlLmltYWdlLzU1MWY2NGVkM2YyYWIyMzQzNzNjODQ2NS5qcGVnIn0sWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMCw1MTIwMDAwXSx7ImNvbnRlbnQtdHlwZSI6ImltYWdlL2pwZWcifSx7IngtYW16LWFsZ29yaXRobSI6IkFXUzQtSE1BQy1TSEEyNTYifSx7IngtYW16LWNyZWRlbnRpYWwiOiJBS0lBSjNaNEFXTTVKTzZBSUxZUS8yMDE1MDQwNC91cy1lYXN0LTEvczMvYXdzNF9yZXF1ZXN0In0seyJ4LWFtei1kYXRlIjoiMjAxNTA0MDRUMDQxMzMzWiJ9LHsieC1hbXotc2VydmVyLXNpZGUtZW5jcnlwdGlvbiI6IkFFUzI1NiJ9LHsic3VjY2Vzc19hY3Rpb25fc3RhdHVzIjoiMjAxIn1dfQ==">   
    <input type="file" name="file">
</form>
```

> ## 📘Note
>
> Response codes from the AWS S3 (5) upload location are xml. See [Amazon S3 Error Responses](http://docs.aws.amazon.com/AmazonS3/latest/API/ErrorResponses.html).

If a File property has been updated, but the user logs out or cannot otherwise complete the upload within a period of time, the upload window may expire. Without having to reset the file property, facet uploads can be *refreshed*, to produce new upload information that can be used to initiate or continue an upload. To do so, update the file property **directly** with a refresh parameter. The json body must contain the facet names of the target uploads, and the response will contain an array of uploads that were refreshed.Example

```
// PUT accounts/5516ee2634d8d93428169c0e/image/refresh 

Request: 
    ["content"]        
Response:         
    {
        "data": [{
            "fields": [... /* updated form fields */ ],
            "filename": "image.jpg",
            "location": 5,
            "maxFileSize": 5120000,
            "name": "content",
            "state": 0,
            "uploadKey": "file",
            "uploadMethod": "post",
            "uploadUrl": "https://medable-v2-uploads.s3.amazonaws.com"
        }],
        "hasMore": false,
        "object": "list"
    }
```