# File basics

The [Files resource](/digital-river-api-reference/2021-12-13/files.md) represents a customer-related document that is hosted on Digital River's servers. You can use the [Files API](/digital-river-api-reference/2021-12-13/files.md) to upload, retrieve, search for, download, and delete files.

Every [File object](#the-file-object) contains a unique identifier, which you can use to [download a file for internal use](#downloading-a-file-for-internal-use) or [create a publicly-accessible link to a document](#creating-a-publicly-accessible-link).

## Creating a file

To upload a customer's tax documents to our servers, [define a file](#defining-a-file) and then [submit a create file request](#submitting-a-create-file-request).

### Defining a file

When defining a file, you're only required to designate a [file and its purpose](#file-and-purpose). Providing a [name and title](#name-and-title), along with specifying a [link expiration time](#link-expiration), are optional values.

#### File and purpose

In the request, `file` should adhere to the [RFC 2388](https://tools.ietf.org/html/rfc2388) specification, which defines file transfers for the multipart/form-data protocol.

The `purpose` parameter should describe the function of the file.

If you're providing Digital River with a customer's tax document, set `purpose` to `tax_document_customer_upload`. For details, refer to [Collecting tax certificates](https://docs.digitalriver.com/digital-river-api/customer-management/setting-tax-related-attributes#collecting-tax-certificate-information) on the [Setting up tax exemptions](https://docs.digitalriver.com/digital-river-api/customer-management/setting-tax-related-attributes) page.

{% hint style="info" %}
For some [orders](/digital-river-api-reference/2021-12-13/orders.md), Digital River generates a [file](/digital-river-api-reference/2021-12-13/files.md) whose `purpose` is `customer_tax_invoice` and/or `customer_credit_memo`. For details, refer to [Accessing invoices and credit memos](https://docs.digitalriver.com/digital-river-api/order-management/accessing-invoices-and-credit-memos).
{% endhint %}

#### Name and title

In the request, you have the option of sending a `fileName` that is suitable for saving to a filesystem as well as a user-friendly `title` for the document.

#### Link expiration

If you provide a `linkExpiresTime`, make sure the value adheres to the [date and time format](/digital-river-api-reference/digital-river-api-reference-guide/api-structure.md#dates-and-times) used in the Digital River APIs.

### Submitting a create file request

In your [`POST /files`](/digital-river-api-reference/2021-12-13/files.md#files-1) requests, set the `Content-Type` header to `multipart/form-data`:

{% tabs %}
{% tab title="POST /files" %}

```
curl https://api.digitalriver.com/files \
     -u <API_key>: \
     -d file="@/path/file.jpg" \
     -d purpose="tax_document_customer_upload" \
     -d fileName="file.png" \
     -d title="My 2019 Tax Certificate."
```

{% endtab %}
{% endtabs %}

A `201 Created` response returns a [File object](#the-file-object):

{% tabs %}
{% tab title="File" %}

```javascript
{
  "id": "file_09e2464f-9b4f-482b-ae89-732183c705be",
  "createdTime": "2018-04-25T20:36:00Z",
  "fileName": "file.png",
  "purpose": "tax_document_customer_upload",
  "title": "My 2019 Tax Certificate.",
  "size": 72334,
  "type": "png",
  "url": "https://files.digitalriver.com/files/file_17a0cab7-1ff7-478e-99f9-d4e753dec24d/contents",
  "liveMode": false
}
```

{% endtab %}
{% endtabs %}

## The File object

{% tabs %}
{% tab title="File" %}

```javascript
{
    "id": "62e30acb-1c24-40fc-8a98-db8e3d479c78",
    "createdTime": "2021-05-24T09:10:49Z",
    "fileName": "GCINIE6426071CGB20190000000000284082939532120039586.pdf",
    "links": [
        {
            "id": "7e20a925-32b1-434b-b704-366b19b8afd2",
            "createdTime": "2021-05-24T22:11:54Z",
            "expired": false,
            "expiresTime": "2021-05-26T13:47:13Z",
            "liveMode": false,
            "url": "https://files-test.digitalriver.com/links/7e20a925-32b1-434b-b704-366b19b8afd2"
        }
    ],
    "purpose": "customer_invoice",
    "title": "customer invoice",
    "size": 35776,
    "type": "pdf",
    "url": "https://api.digitalriver.com/files/62e30acb-1c24-40fc-8a98-db8e3d479c78/content",
    "liveMode": false
}
```

{% endtab %}
{% endtabs %}

### Unique identifier

You can use `id` to [retrieve](/digital-river-api-reference/2021-12-13/files.md#files-id), [search for](/digital-river-api-reference/2021-12-13/files.md#files), and [delete files](/digital-river-api-reference/2021-12-13/files.md#files-id-1). You'll also need it to [create a file link](/digital-river-api-reference/2021-12-13/files/file-basics.md#creating-a-file) to share with customers.

### Links

Files may contain an array of publicly accessible [file links](/digital-river-api-reference/2021-12-13/file-links.md). If no links have been generated, however, then `links[]` does not exist.

<div align="left"><figure><img src="/files/fchBQlkjproL1QljI9Aj" alt=""><figcaption></figcaption></figure></div>

### Size and type

A file's `size` is represented in bytes, and its `type` signifies a format (e.g. pdf, jpg, or png).

### URL

The `url` allows you to [download a file for internal use](#downloading-a-file-for-internal-use).

## Using a file

Once a file is created, you can [download it for internal use](#downloading-a-file-for-internal-use) or [create a publicly accessible link](#creating-a-publicly-accessible-link).

### Downloading a file for internal use

You can use [`url`](#url) to download a document for internal use. But to [get the file's content](/digital-river-api-reference/2021-12-13/files.md#files-id-content), you must provide your [secret (confidential) API key](/digital-river-api-reference/digital-river-api-reference-guide/api-structure.md#confidential-keys).

A request sent with the wrong key returns a `401 Unauthorized` response status code.

{% tabs %}
{% tab title="GET /files/{fileId}/content" %}

```javascript
{
    "type": "unauthorized",
    "errors": [
        {
            "message": "An authorization error has occurred."
        }
    ]
}
```

{% endtab %}
{% endtabs %}

As a result, don't share `url` with your customers. [Create a public link](#creating-a-publicly-accessible-link) if you'd like to provide them access to a document.

### Creating a publicly accessible link

To share files with customers, [create a file link](/digital-river-api-reference/2021-12-13/file-links.md#file-links-1).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digitalriver.com/digital-river-api-reference/2021-12-13/files/file-basics.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.