> ## Documentation Index
> Fetch the complete documentation index at: https://signatureapi-daf4ee54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Upload

> Store PDF, DOCX, or PNG files in SignatureAPI and reference them as document sources in envelopes.

An upload is a file stored in SignatureAPI. You can use an upload as the source file for a document in an envelope. Uploads are the simplest way to supply document files when you do not want to host them yourself.

After uploading a file, pass the returned `url` value as the `url` property of a [document](/docs/api/resources/documents/object).

The following file formats are supported:

| Format | Media Type                                                                |
| ------ | ------------------------------------------------------------------------- |
| PDF    | `application/pdf`                                                         |
| DOCX   | `application/vnd.openxmlformats-officedocument.wordprocessingml.document` |
| PNG    | `image/png`                                                               |

## Retention

Uploads have one of two retention types, indicated by the `retention` property:

| Retention | Description                                                                                                                                                                                                                                                                   |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Temporary | Created through the API. Automatically deleted 24 hours after creation. Use this for one-time document sends.                                                                                                                                                                 |
| Permanent | Stored indefinitely and reusable across multiple envelopes. Identified by a unique `key`. Created by [storing an upload](/docs/api/resources/uploads/store) through the API or uploading through the [Library](https://dashboard.signatureapi.com/library) in your dashboard. |

<Info>
  The Upload resource replaces the [File resource](/docs/api/resources/files/object). The File resource is soft-deprecated but remains available for backward compatibility.
</Info>

## Attributes

<ResponseField name="id" type="string" required>
  The unique identifier of the upload.
</ResponseField>

<ResponseField name="retention" type="enum" required>
  The retention type of the upload.

  | Value       | Description                                                                                                                          |
  | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ |
  | `temporary` | The file is automatically deleted 24 hours after creation.                                                                           |
  | `permanent` | The file is stored indefinitely. Created by [storing an upload](/docs/api/resources/uploads/store) or through the dashboard library. |
</ResponseField>

<ResponseField name="key" type="string">
  A unique identifier for the upload within your account. Present only on permanent uploads (`retention` is `permanent`).

  Only lowercase letters, numbers, hyphens, and underscores are allowed. Maximum 100 characters.
</ResponseField>

<ResponseField name="url" type="string" required>
  The internal URL used to reference this upload in other API calls, such as `document.url`.

  You cannot use this URL to download the file directly.
</ResponseField>

<ResponseField name="format" type="enum" required>
  The file format of the upload.

  | Value  | Description                                                                              |
  | ------ | ---------------------------------------------------------------------------------------- |
  | `pdf`  | A PDF file (`application/pdf`).                                                          |
  | `docx` | A DOCX file (`application/vnd.openxmlformats-officedocument.wordprocessingml.document`). |
  | `png`  | A PNG image (`image/png`).                                                               |
</ResponseField>

<ResponseField name="sha_256" type="string" required>
  The SHA-256 hash of the uploaded file, in hexadecimal format.
</ResponseField>

<ResponseField name="size" type="integer" required>
  The size of the uploaded file in bytes. Maximum 5 MB (5,242,880 bytes).
</ResponseField>

<ResponseField name="created_at" type="string" required>
  The date and time when the upload was created, in ISO 8601 format.
</ResponseField>

<ResponseField name="expires_at" type="string">
  The date and time when the upload will be automatically deleted, in ISO 8601 format. Present only on temporary uploads (`retention` is `temporary`). The expiration is 24 hours after creation.
</ResponseField>

<ResponseExample>
  ```json Temporary upload theme={null}
  // HTTP Status Code 200

  {
    "id": "upl_1sAAaVfabdt0esVjmSTmLA",
    "retention": "temporary",
    "url": "https://api.signatureapi.com/v1/uploads/upl_1sAAaVfabdt0esVjmSTmLA",
    "format": "pdf",
    "sha_256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "size": 102400,
    "created_at": "2025-12-30T12:00:00.000Z",
    "expires_at": "2025-12-31T12:00:00.000Z"
  }
  ```

  ```json Permanent upload theme={null}
  // HTTP Status Code 200

  {
    "id": "upl_3joO7lxE8HVhOZmkCHFCxK",
    "retention": "permanent",
    "key": "contract-template-v2",
    "url": "https://api.signatureapi.com/v1/uploads/upl_3joO7lxE8HVhOZmkCHFCxK",
    "format": "docx",
    "sha_256": "abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789",
    "size": 234567,
    "created_at": "2025-12-30T12:00:00.000Z"
  }
  ```
</ResponseExample>