---
updatedAt: 2025-11-13T14:14:44.000Z
agentTools:
  siteIndex: https://docs.affirm.com/llms.txt
  projectIndex: https://docs.affirm.com/developers/llms.txt
---

# About Partner Files API

# Overview

The [Partner Files API](https://docs.affirm.com/developers/reference/partner-files-api) enables merchants to both upload and download files pertaining to their disputes. The Partner Files API provides you with the following actions:

* **[Upload Dispute Evidence (Upload File)](https://docs.affirm.com/developers/reference/about-partner-files-api#upload-dispute-evidence-upload-file)**
* **[Download Dispute Evidence (Download File)](https://docs.affirm.com/developers/reference/about-partner-files-api#download-dispute-evidence-download-file)**

Explore the sections below to learn about the files endpoints and their requirements.

***

## Basic Requirements

### Authentication

All Partner Files API endpoints require partner authentication.

### Idempotency

For idempotent requests, the idempotency key has an **expiration date of 24 hours**. Idempotency keys are passed in using the **Idempotency-Key header**.

***

## Upload Dispute Evidence (Upload File)

<span style={{ color: "blue" }}>POST</span> **/api/partner/v1/files**

This endpoint is designed to upload the file (evidence) by making a multipart/form-data request on an open dispute.

Idempotency: *Yes*

**Request Body Parameters**:

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Field Name
      </th>

      <th>
        Data Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `file_name` <span style={{ color: "red" }}>required</span>
      </td>

      <td>
        string
      </td>

      <td>
        Name of the file. The filename can be a maximum length of 25 characters long and may include alphanumeric characters, hyphens, underscores, spaces, and periods.
      </td>
    </tr>

    <tr>
      <td>
        `file` <span style={{ color: "red" }}>required</span>
      </td>

      <td>
        string
      </td>

      <td>
        A file to upload (binary format).
      </td>
    </tr>

    <tr>
      <td>
        `purpose` <span style={{ color: "red" }}>required</span>
      </td>

      <td>
        string
      </td>

      <td>
        An enum indicating the purpose of the uploaded file. Additional purpose enums can be added depending on the use case\
        Value:  

        \-`dispute_evidence`
      </td>
    </tr>

    <tr>
      <td>
        `merchant_id`
      </td>

      <td>
        string
      </td>

      <td>
        The ID of the merchant that the file is associated with.
      </td>
    </tr>
  </tbody>
</Table>

<br />

**Response Object**:

<Table align={["left","left","left"]}>
  <thead>
    <tr>
      <th>
        Field Name
      </th>

      <th>
        Data Type
      </th>

      <th>
        Description
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>
        `file_id`
      </td>

      <td>
        string
      </td>

      <td>
        ID of the file.
      </td>
    </tr>

    <tr>
      <td>
        `created`
      </td>

      <td>
        string
      </td>

      <td>
        Time at which the file is uploaded, in ISO 8601 UTC format.
      </td>
    </tr>

    <tr>
      <td>
        `purpose`
      </td>

      <td>
        string
      </td>

      <td>
        The purpose of the file. Possible values:  

        \-`dispute_evidence`
      </td>
    </tr>

    <tr>
      <td>
        `file_name`
      </td>

      <td>
        string
      </td>

      <td>
        Name of the file.
      </td>
    </tr>
  </tbody>
</Table>

<br />

**File Purpose Restrictions**:

| Field Purpose      | Supported Mimetypes | Max Size |
| :----------------- | :------------------ | :------- |
| `dispute_evidence` | PDF                 | 11MB     |

***

## Download Dispute Evidence (Download File)

<span style={{ color: "green" }}>GET</span> **/api/partner/v1/files/`{file_id}`**

Idempotency:  *No*

**Request Body Parameters**:

| Field Name    | Data Type | Description                                                                                                                                                     |
| :------------ | :-------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `merchant_id` | string    | The ID of the merchant that the file is associated with. `merchant_id` is required *if* the file is uploaded with a merchant\_id in POST /api/partner/v1/files. |

<br />

**Response Object**:

| Field Name                | Data Type | Description                                                                              |
| :------------------------ | :-------- | :--------------------------------------------------------------------------------------- |
| `id`                      | string    | Unique identifier for the File object.                                                   |
| `download_url`            | string    | The URL from which the file can be downloaded.                                           |
| `download_url_expires_at` | timestamp | A future timestamp after which the `download_url` will no longer be usable. (15 minutes) |

# Sibling pages

* [Partner Files API](https://docs.affirm.com/developers/reference/partner-files-api.md)