# File Uploads and File Links

This section details how to manage file uploads and create file links within the Stripe ecosystem. It covers uploading various types of files to Stripe for purposes such as dispute evidence, identification documents, and business assets. Additionally, it explains how to generate secure, unauthenticated links to these files for sharing with non-Stripe users.

## File Uploads

Stripe's File Upload API allows you to securely send files to Stripe. These files can be used for various purposes, including dispute evidence, identification documents, and business assets.

### Uploading a File

To upload a file, you need to send a `multipart/form-data` request to `https://files.stripe.com/v1/files`. This endpoint is distinct from most other Stripe API endpoints. The request must include a `purpose` and the `file` itself.

**Example using `curl`:**

```bash
curl https://files.stripe.com/v1/files \
  -u sk_test_RXHltS2OKzISvxWQ7NmRN57i001oa6x7o4: \
  -F "file"="@/path/to/a/file.jpg" \
  -F "purpose"="dispute_evidence"
```

**Example using Android SDK (Kotlin):**

```kotlin
class CheckoutActivity : AppCompatActivity() {
    private val stripe: Stripe by lazy {
        Stripe(this, "pk_test_51FeMfIG3Ks4CHLRJvYOjBLY05dmeTT9oZLxqTspUtTlGyNv3EQDbyBPPRMY9vf72LOE4ZEWZMP5I5uoULSG49IPe00tasHNr6j")
    }

    private fun uploadFile(file: File) {
        stripe.createFile(
            StripeFileParams(
                file,
                StripeFilePurpose.DisputeEvidence
            ),
            callback = object : ApiResultCallback<StripeFile> {
                override fun onSuccess(result: StripeFile) {
                    // File upload succeeded
                }
                override fun onError(e: Exception) {
                    // File upload failed
                }
            }
        )
    }
}
```

#### File Purpose and Requirements

Each file purpose has specific requirements for supported MIME types and maximum file sizes.

| Purpose                       | Description                                                               | Supported mimetypes | Max size | Expiry   | Downloadable |
| :---------------------------- | :------------------------------------------------------------------------ | :------------------ | :------- | :------- | :----------- |
| `account_requirement`         | Additional documentation requirements that can be requested for an account. | PDF, JPEG, PNG      | 64MB     | NEVER    | No           |
| `business_icon`               | A business icon.                                                          | JPEG, PNG, GIF      | 512KB    | NEVER    | Yes          |
| `business_logo`               | A business logo.                                                          | JPEG, PNG, GIF      | 512KB    | NEVER    | Yes          |
| `customer_signature`          | Customer signature image.                                                 | JPEG, PNG, SVG      | 4MB      | 7 days   | Yes          |
| `dispute_evidence`            | Evidence to submit with a dispute response.                               |                     |          |          |              |
| `finance_report_run`          | User-accessible copies of query results from the Reporting dataset.       | CSV                 | 100MB    | 90 days  | Yes          |
| `financial_account_statement` | Financial account statements.                                             | PDF                 | 100MB    | NEVER    | Yes          |
| `identity_document`           | A document to verify the identity of an account owner during account provisioning. | PDF, JPEG, PNG      | 10MB     | NEVER    | No           |
| `identity_document_downloadable` | Image of a document collected by Stripe Identity.                         | JPEG, PNG           | 10MB     | NEVER    | Yes          |
| `issuing_regulatory_reporting` | Additional regulatory reporting requirements for Issuing.                 | CSV                 | 100MB    | NEVER    | No           |
| `pci_document`                | A self-assessment PCI questionnaire.                                      | PDF                 | 10MB     | NEVER    | No           |
| `platform_terms_of_service`   | A copy of the platform’s Terms of Service.                                | PDF                 | 10MB     | NEVER    | No           |
| `selfie`                      | A selfie of the account owner.                                            | JPEG, PNG           | 10MB     | NEVER    | No           |
| `sigma_scheduled_query`       | Results of a Sigma scheduled query.                                       | CSV                 | 100MB    | 90 days  | Yes          |
| `tax_document_user_upload`    | A document uploaded by the user to satisfy tax requirements.              | PDF, JPEG, PNG      | 10MB     | NEVER    | No           |
| `terminal_android_apk`        | Android application for Stripe Terminal.                                  | APK                 | 50MB     | NEVER    | Yes          |
| `terminal_reader_splashscreen`| A custom splash screen for Stripe Terminal readers.                       | JPEG, PNG           | 1MB      | NEVER    | Yes          |

## File Links

File Links allow you to share the contents of a `File` object with non-Stripe users via a URL. These URLs do not require authentication to access.

### Creating a File Link

You can create a new File Link object by making a `POST` request to `/v1/file_links`.

**Parameters:**

*   `file` (string, required): The ID of the file for which to create a link. The file's purpose must be one of the supported types (e.g., `business_icon`, `dispute_evidence`).
*   `expires_at` (timestamp, optional): A future timestamp after which the link will no longer be usable.
*   `metadata` (object, optional): A set of key-value pairs to attach to the object.

**Example `curl`:**

```bash
curl https://api.stripe.com/v1/file_links \
  -u "sk_test_RXHltS2OKzISvxWQ7NmRN57i001oa6x7o4:" \
  -d file={{FILE_ID}}
```

**Response:**

```json
{
  "id": "link_1Mr23jLkdIwHu7ix65betcoo",
  "object": "file_link",
  "created": 1680108075,
  "expired": false,
  "expires_at": null,
  "file": "file_1Mr4LDLkdIwHu7ixFCz0dZiH",
  "livemode": false,
  "metadata": {},
  "url": "https://files.stripe.com/links/MDB8YWNjdF8xTTJKVGtMa2RJd0h1N2l4fGZsX3Rlc3RfaXVoY2hrUnJPMzlBR3dPb01XMmFkSTVq00yUPLFf3h"
}
```

### Retrieving a File Link

You can retrieve a specific File Link object by its ID using a `GET` request to `/v1/file_links/:id`.

**Example `curl`:**

```bash
curl https://api.stripe.com/v1/file_links/{{FILE_LINK_ID}} \
  -u "sk_test_RXHltS2OKzISvxWQ7NmRN57i001oa6x7o4:"
```

### Updating a File Link

You can update an existing File Link, for example, to set an expiration time. Expired links cannot be updated. Use a `POST` request to `/v1/file_links/:id`.

**Parameters:**

*   `expires_at` (string or timestamp, optional): A future timestamp after which the link will no longer be usable, or `now` to expire the link immediately.
*   `metadata` (object, optional): A set of key-value pairs to attach to the object.

**Example `curl`:**

```bash
curl https://api.stripe.com/v1/file_links/{{FILE_LINK_ID}} \
  -u "sk_test_RXHltS2OKzISvxWQ7NmRN57i001oa6x7o4:" \
  -d "metadata[order_id]=6735"
```

### Listing File Links

You can retrieve a list of File Links associated with your account using a `GET` request to `/v1/file_links`.

**Parameters:**

*   `created` (object, optional): Filter by creation date.
*   `ending_before` (string, optional): A cursor for use in pagination.
*   `expired` (boolean, optional): Filter by expired status.
*   `file` (string, optional): Filter by the file ID.
*   `limit` (integer, optional): A limit on the number of objects to be returned.
*   `starting_after` (string, optional): A cursor for use in pagination.

**Example `curl`:**

```bash
curl -G https://api.stripe.com/v1/file_links \
  -u "sk_test_RXHltS2OKzISvxWQ7NmRN57i001oa6x7o4:" \
  -d limit=3
```

## The File Object

The File object represents files hosted on Stripe's servers. Files can be uploaded by you (e.g., for dispute evidence) or created by Stripe independently (e.g., Sigma query results).

### File Attributes

*   `id` (string): Unique identifier for the object.
*   `purpose` (enum): The purpose of the uploaded file.
*   `type` (nullable string): The returned file type (e.g., `csv`, `pdf`, `jpg`, `png`).
*   `created` (timestamp): Timestamp of when the file was created.
*   `expires_at` (nullable timestamp): Timestamp when the file will expire.
*   `filename` (nullable string): The original filename of the uploaded file.
*   `links` (nullable object): A list of file links associated with this file.
*   `size` (integer): The size of the file in bytes.
*   `title` (nullable string): A user-friendly title for the file.
*   `url` (nullable string): The URL to access the file's contents.

### Creating a File

To upload a file, send a `multipart/form-data` request to `/v1/files`.

**Parameters:**

*   `file` (object, required): The file to upload.
*   `purpose` (enum, required): The purpose of the file.
*   `file_link_data` (object, optional): Data to create a file link.

**Example `curl`:**

```bash
curl https://files.stripe.com/v1/files \
  -u sk_test_RXHltS2OKzISvxWQ7NmRN57i001oa6x7o4: \
  -F purpose=dispute_evidence \
  -F file="@/path/to/a/file.jpg"
```

### Retrieving a File

Retrieve the details of an existing file object using its ID with a `GET` request to `/v1/files/:id`.

**Example `curl`:**

```bash
curl https://api.stripe.com/v1/files/{{FILE_ID}} \
  -u "sk_test_RXHltS2OKzISvxWQ7NmRN57i001oa6x7o4:"
```

### Listing Files

Get a list of files accessible by your account with a `GET` request to `/v1/files`. Files are sorted by creation date, with the most recent first.

**Parameters:**

*   `purpose` (string, optional): Filter by the file purpose.
*   `created` (object, optional): Filter by creation date.
*   `ending_before` (string, optional): A cursor for use in pagination.
*   `limit` (integer, optional): A limit on the number of objects to be returned.
*   `starting_after` (string, optional): A cursor for use in pagination.

**Example `curl`:**

```bash
curl -G https://api.stripe.com/v1/files \
  -u "sk_test_RXHltS2OKzISvxWQ7NmRN57i001oa6x7o4:" \
  -d limit=3
```